macOS环境下Jenkins执行fastlane截图命令失败，本地终端正常

开发者阿泽

2026-5-20

我之前在Jenkins（macOS）上跑fastlane的screengrab/snapshot时也踩过几乎一样的坑——本地跑完全正常，一到Jenkins就各种报错，给你分享下我解决这两个平台问题的具体步骤：

Android 端：ANDROID_SDK_ROOT 找不到的问题

本地终端会自动加载你个人的shell配置文件（比如~/.zshrc或~/.bash_profile），里面已经配置好了ANDROID_SDK_ROOT环境变量，但Jenkins默认不会读取这些用户级别的配置，导致运行脚本时找不到SDK路径。

方案一：在Jenkins全局配置里添加环境变量
进入Jenkins → 系统管理 → 系统配置，找到「全局属性」板块，勾选「环境变量」，添加两条配置：
- 键：ANDROID_SDK_ROOT，值：你的Android SDK实际路径（比如/Users/Shared/Jenkins/Library/Android/sdk，如果是用本地用户跑Jenkins，直接用你本地终端执行echo $ANDROID_SDK_ROOT输出的路径即可）
- 键：PATH，值：在原有基础上追加$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools，避免其他Android工具找不到的问题
方案二：在.sh脚本开头手动导出变量
在你的截图脚本最前面加上这两行（替换成你的实际SDK路径）：
```
export ANDROID_SDK_ROOT=/Users/your-user/Library/Android/sdk
export PATH=$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools:$PATH
```
另外要注意Jenkins运行用户对SDK目录的读写权限，有时候权限不足也会导致无法访问AVD路径，可以用chmod -R 755 /path/to/android/sdk给目录加权限试试。

本地是用你的个人用户运行fastlane，能直接访问钥匙串里的开发者证书和已安装的配置描述文件，但Jenkins有独立的运行上下文，默认没有权限访问这些资源，导致构建测试时找不到正确的配置。

1. 解锁Jenkins用户的钥匙串
在执行fastlane命令前，先添加解锁钥匙串的命令（替换成你的钥匙串密码和路径）：
```
security unlock-keychain -p "your-keychain-password" /Users/your-user/Library/Keychains/login.keychain-db
```
如果Jenkins是用系统的jenkins用户运行，钥匙串路径可能是/Users/Shared/Jenkins/Library/Keychains/login.keychain-db。
2. 用fastlane match统一管理证书和描述文件
这是最省心的方案，能彻底避免手动配置的麻烦。先在本地初始化match：
```
fastlane match init
```
按照提示创建一个私有仓库存储证书和描述文件，然后在你的Fastfile里添加：
```
before_all do
  match(type: "development") # 跑测试用development，发布用appstore
end
```
这样Jenkins运行fastlane时，会自动从仓库下载并安装需要的证书和描述文件，不用手动配置。
3. 确保Jenkins的Xcode配置正确
进入Jenkins → 系统管理 → 全局工具配置，找到Xcode配置，选择和你本地一致的Xcode版本，指定正确的路径（比如/Applications/Xcode.app），同时确保已经接受Xcode的许可协议，可以在脚本里加一行：
```
sudo xcodebuild -license accept
```

4. 修复钥匙串分区权限
有时候即使解锁了钥匙串，Xcode还是无法访问证书，可以添加这条命令调整权限：

security set-key-partition-list -S apple-tool:,apple: -s -k "your-keychain-password" /Users/your-user/Library/Keychains/login.keychain-db

内容的提问来源于stack exchange，提问作者Son Nguyen