ffmpeg-kit-react-native Android 构建配置

背景

也就是 ffmpeg-kit-react-native 这个库准删除状态已经装不到东西了，所以需要本地依赖。下面是prompt，大师果然不用emoji。题目我改了下太空洞了不实际。

作为语言大师及技术专家的校色，来吧上面的那么多的改动和参考，总结一篇精炼的blog。

在 Windows 环境下使用 React Native 开发 Android 应用时，经常会遇到各种构建问题：依赖包版本被移除、SDK 版本冲突、中文/日文路径乱码、临时文件路径问题等。本文总结了一套完整的解决方案。

核心问题与解决方案

1. 使用本地 AAR 文件替代远程依赖

场景：npm 包（如 ffmpeg-kit-react-native）依赖的 Android 库版本在 Maven 仓库中已被移除。

解决方案：

1. 下载 AAR 文件并放置到 android/libs/ 目录

2. 配置仓库（三处配置）：

android/build.gradle：

buildscript {
    // ... 其他配置

    allprojects {
        repositories {
            google()
            mavenCentral()
            flatDir {
                dirs "$rootDir/libs"
            }
        }
    }
}

android/app/build.gradle：

android {
    // ... 其他配置

    repositories {
        flatDir {
            dirs "$rootDir/libs"
        }
    }
}

dependencies {
    implementation(name: 'ffmpeg-kit-full-gpl', ext: 'aar')
    implementation 'com.arthenica:smart-exception-java:0.2.1'
}

node_modules/ffmpeg-kit-react-native/android/build.gradle：

repositories {
    mavenCentral()
    google()

    flatDir {
        dirs "$rootDir/libs"
    }

    // ... 其他配置
}

2. 统一 SDK 和 NDK 版本

问题：第三方库硬编码了不同的 SDK/NDK 版本，导致编译失败。

解决方案：

修改 node_modules/ffmpeg-kit-react-native/android/build.gradle：

android {
    // 使用项目统一配置，而非硬编码
    compileSdkVersion rootProject.ext.compileSdkVersion

    defaultConfig {
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        // ...
    }
}

修改 android/build.gradle（NDK 版本与本地安装一致）：

ext {
    ndkVersion = "27.0.12077973"  // 使用已安装的版本
    // ...
}

可选：删除 android/local.properties 中的 ndk.dir 配置，让 Gradle 自动管理。

3. Windows 环境编码与路径优化

问题：

• 控制台显示日文/中文乱码
• 默认临时目录路径过长或包含中文用户名
• Gradle 缓存目录在用户目录下

解决方案：

android/gradle.properties 完整配置：

# 自定义 Gradle 主目录
gradle.user.home=C\:\\mys\\gradle

# JVM 参数：内存、编码、临时目录
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8 -Dconsole.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -Djava.io.tmpdir=C\:\\mys\\temp

# AndroidX 支持
android.useAndroidX=true

# 架构配置（移除 x86 可减少构建问题）
reactNativeArchitectures=armeabi-v7a,arm64-v8a

# 新架构、Hermes 等
newArchEnabled=true
hermesEnabled=true

设置系统环境变量：

# 以管理员身份运行 PowerShell
[Environment]::SetEnvironmentVariable("TMP", "C:\mys\temp", "User")
[Environment]::SetEnvironmentVariable("TEMP", "C:\mys\temp", "User")
[Environment]::SetEnvironmentVariable("GRADLE_USER_HOME", "C:\mys\gradle", "User")

Android Studio VM 选项（Help → Edit Custom VM Options）：

-Djava.io.tmpdir=C:/mys/temp
-Dfile.encoding=UTF-8
-Dconsole.encoding=UTF-8

4. 持久化 node_modules 修改

问题：每次 npm install 都会覆盖 node_modules 中的修改。

解决方案：使用 patch-package

# 安装
npm install --save-dev patch-package postinstall-postinstall

# 修改完 node_modules 文件后，创建补丁
npx patch-package ffmpeg-kit-react-native

package.json：

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

5. 构建前清理流程

# 1. 停止 Gradle Daemon
cd android
./gradlew --stop

# 2. 清理构建缓存
./gradlew clean
rm -rf .gradle build app/build

# 3. 清理 node_modules（可选）
cd ..
rm -rf node_modules
npm install

# 4. 重新构建
npx react-native run-android

完整配置检查清单

• [ ] AAR 文件放置到 android/libs/
• [ ] 三处 build.gradle 都配置了 flatDir
• [ ] SDK/NDK 版本统一使用 rootProject.ext
• [ ] gradle.properties 配置了编码和路径
• [ ] 创建了自定义目录：C:\mys\temp、C:\mys\gradle
• [ ] 设置了系统环境变量
• [ ] 使用 patch-package 保存 node_modules 修改
• [ ] Android Studio VM 选项已配置

常见错误速查

错误信息	解决方案
Could not find ffmpeg-kit-*	配置 flatDir 并放置 AAR 文件
Could not find compile target android-33	统一使用 rootProject.ext.compileSdkVersion
NDK version disagrees	修改 ndkVersion 或删除 ndk.dir
控制台乱码	添加编码相关 JVM 参数
prefab_command.bat 错误	移除 x86 架构或添加 ndk.abiFilters

总结

通过系统性地配置本地依赖、统一版本管理、优化编码环境和路径设置，可以显著改善 React Native Android 在 Windows 环境下的开发体验。关键是理解各个配置的作用域和优先级，确保项目、第三方库、Gradle、Android Studio 和系统环境的一致性。

---

提示：本文配置基于 React Native 0.82+、Android Gradle Plugin 8.x、NDK 27.x。不同版本可能需要适当调整。