React Native iOS构建：Jenkins执行xcodebuild报错无法解析empty-module.js

问题场景 #

本地MacOS终端执行以下命令可正常构建React Native iOS应用：

xcodebuild archive -workspace MyProject.xcworkspace -derivedDataPath build -scheme MyProject -archivePath $PWD/build-artifacts/MyProject.xcarchive -configuration Release CODE_SIGN_STYLE='Automatic' BITCODE_GENERATION_MODE='bitcode'

但通过Jenkins的「Execute shell」步骤执行相同命令时，出现metro模块找不到的错误：

error Unable to resolve module /Users/mike/git/my-project/node_modules/react-native/node_modules/metro-runtime/src/modules/empty-module.js from /Users/mike/git/my-project/_:

None of these files exist:

• ../my-project/node_modules/react-native/node_modules/metro-runtime/src/modules/empty-module.js(.native|.native.js|.js|.native.json|.json|.native.ts|.ts|.native.tsx|.tsx)
• ../my-project/node_modules/react-native/node_modules/metro-runtime/src/modules/empty-module.js/index(.native|.native.js|.js|.native.json|.json|.native.ts|.ts|.native.tsx|.tsx)
  ...（堆栈信息省略）

已确认系统与Jenkins的node、npm等工具PATH一致，以下是可行的解决方向：

1. 修正Jenkins工作目录的路径问题 #

错误日志中的../my-project/路径说明构建时的工作目录与本地终端不一致。Jenkins默认工作目录是项目工作空间根目录，而本地是在项目目录下执行命令。在shell步骤开头先切换到项目目录：

cd /Users/mike/git/my-project
# 再执行原构建命令
xcodebuild archive -workspace MyProject.xcworkspace -derivedDataPath build -scheme MyProject -archivePath $PWD/build-artifacts/MyProject.xcarchive -configuration Release CODE_SIGN_STYLE='Automatic' BITCODE_GENERATION_MODE='bitcode'

或者使用Jenkins内置的$WORKSPACE变量确保路径正确：

cd $WORKSPACE
# 执行构建命令

2. 清理并重新安装依赖 #

Jenkins工作空间可能残留旧依赖或损坏的缓存，导致metro解析异常。在构建前添加清理步骤：

# 清理旧依赖和锁文件
rm -rf node_modules
rm -f package-lock.json yarn.lock

# 重新安装JS依赖
npm install
# 若使用yarn则替换为 yarn install

# 安装iOS原生依赖（React Native 0.60+ 必需）
npx pod-install ios

注意确保Jenkins用户对项目目录有读写权限。

3. 显式设置关键环境变量 #

除PATH外，NODE_ENV、HOME等环境变量可能影响metro的路径解析。在shell步骤开头添加：

export NODE_ENV=production
export HOME=/Users/mike # 指定Jenkins使用的用户home目录，避免缓存路径混乱

4. 清理Metro缓存 #

Metro的缓存可能存在损坏，在构建前重置缓存：

npx react-native start --reset-cache

或者直接删除Metro的全局缓存目录：

rm -rf ~/.metro-cache

5. 排查Jenkins额外配置干扰 #

部分Jenkins插件（如凭证管理插件）可能修改环境变量导致路径解析错误，可临时禁用这些额外配置，测试是否能正常构建。

内容的提问来源于stack exchange，提问作者mikeb-meq