Shenzhen 开源项目使用教程：iOS应用构建与分发的终极命令行工具
项目地址: https://gitcode.com/gh_mirrors/sh/shenzhen 痛点：iOS应用分发的手动噩梦
你是否还在Xcode中反复点击"Archive"、"Export"、"Upload"按钮来完成iOS应用的构建和分发？每次发布测试版本都需要经历繁琐的手工操作，浪费宝贵开发时间？Shenzhen正是为解决这一痛点而生！
Shenzhen是一个强大的命令行工具，专门用于自动化构建.ipa文件和分发iOS应用到各种平台。它支持多达10种分发渠道，让你的CI/CD流程更加高效。
快速开始：安装与基础使用
环境要求
- macOS系统
- Xcode 4或更高版本
- Ruby 1.9.3+
安装方法
# 使用RubyGems安装
gem install shenzhen
# 如果遇到JSON构建错误（Mac OS X Mavericks + Xcode 5.1）
ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future gem install json
gem install shenzhen
设置环境变量（推荐）
# 设置本地化环境，避免字符编码问题
export LC_ALL="en_US.UTF-8"
核心功能详解
1. 应用构建（Build）
Shenzhen的核心功能是自动化构建iOS应用，生成.ipa文件。
# 进入iOS项目目录
cd /path/to/your/ios-project
# 基本构建命令
ipa build
# 指定工作空间和配置
ipa build --workspace MyApp.xcworkspace --configuration Release
# 自定义输出目录和文件名
ipa build --destination ./builds --ipa MyApp-Release.ipa
# 使用特定证书和描述文件签名
ipa build --embed distribution.mobileprovision --identity "iPhone Distribution: Your Company"
构建参数详解
| 参数 | 说明 | 示例 |
|---|---|---|
-w, --workspace | 指定工作空间文件 | --workspace MyApp.xcworkspace |
-p, --project | 指定项目文件 | --project MyApp.xcodeproj |
-c, --configuration | 构建配置 | --configuration Release |
-s, --scheme | 构建方案 | --scheme MyApp |
-d, --destination | 输出目录 | --destination ./builds |
--ipa | 自定义IPA文件名 | --ipa MyApp-v1.0.ipa |
-m, --embed | 描述文件路径 | --embed dist.mobileprovision |
-i, --identity | 代码签名身份 | --identity "iPhone Distribution" |
2. 多渠道分发（Distribute）
Shenzhen支持10种不同的分发渠道，满足各种测试和发布需求。
分发渠道对比表
| 渠道 | 命令 | 适用场景 | 特点 |
|---|---|---|---|
| HockeyApp | distribute:hockeyapp | 企业内测 | 丰富的测试管理功能 |
| Crashlytics | distribute:crashlytics | 崩溃分析测试 | 深度集成Firebase |
| TestFairy | distribute:testfairy | 用户体验测试 | 屏幕录制和会话回放 |
| DeployGate | distribute:deploygate | 快速内测分发 | 日本市场首选 |
| FIR.im | distribute:fir | 国内快速分发 | 中国开发者常用 |
| 蒲公英 | distribute:pgyer | 国内企业分发 | 中文界面，功能全面 |
| iTunes Connect | distribute:itunesconnect | 正式发布 | App Store审核提交 |
| Amazon S3 | distribute:s3 | 自定义分发 | 灵活的对象存储 |
| FTP/SFTP | distribute:ftp | 自有服务器分发 | 完全控制分发环境 |
| RivieraBuild | distribute:rivierabuild | 持续集成 | CI/CD流水线集成 |
3. 应用信息查看（Info）
快速查看.ipa文件中的移动配置信息：
ipa info MyApp.ipa
# 输出示例：
+-----------------------------+----------------------------------------------------------+
| ApplicationIdentifierPrefix | DJ73OPSO53 |
| CreationDate | 2014-03-26T02:53:00+00:00 |
| Entitlements | application-identifier: DJ73OPSO53.com.company.myapp |
| | aps-environment: production |
| | get-task-allow: false |
| | keychain-access-groups: ["DJ73OPSO53.*"] |
| Name | MyApp Production Profile |
| TeamIdentifier | S6ZYP4L6TY |
| TimeToLive | 365 |
| UUID | P7602NR3-4D34-441N-B6C9-R79395PN1OO3 |
| Version | 1 |
+-----------------------------+----------------------------------------------------------+
实战示例：完整的CI/CD流水线
场景：自动化测试分发流水线
#!/bin/bash
# 设置环境变量
export LC_ALL="en_US.UTF-8"
export HOCKEYAPP_API_TOKEN="your_api_token_here"
# 1. 清理并构建应用
echo "开始构建应用..."
ipa build --workspace MyApp.xcworkspace \
--scheme MyApp \
--configuration Release \
--destination ./builds \
--ipa MyApp-$(date +%Y%m%d-%H%M).ipa
# 2. 上传到HockeyApp
echo "分发应用到HockeyApp..."
ipa distribute:hockeyapp \
--file ./builds/MyApp-*.ipa \
--notes "自动化构建于 $(date)" \
--notify \
--tags "developers,testers"
# 3. 发送通知
echo "构建和分发完成！"
环境变量配置最佳实践
为了避免在命令行中暴露敏感信息，建议使用环境变量：
# ~/.bash_profile 或 ~/.zshrc
export HOCKEYAPP_API_TOKEN="your_hockeyapp_token"
export CRASHLYTICS_API_TOKEN="your_crashlytics_token"
export CRASHLYTICS_BUILD_SECRET="your_build_secret"
export DEPLOYGATE_API_TOKEN="your_deploygate_token"
export DEPLOYGATE_USER_NAME="your_username"
export AWS_ACCESS_KEY_ID="your_aws_key"
export AWS_SECRET_ACCESS_KEY="your_aws_secret"
export ITUNES_CONNECT_ACCOUNT="your_itunes_email"
高级用法与技巧
1. 多环境配置管理
# 开发环境构建
ipa build --configuration Debug --scheme MyApp-Dev
# 预生产环境构建
ipa build --configuration Staging --scheme MyApp-Staging
# 生产环境构建
ipa build --configuration Release --scheme MyApp-Prod
2. 自定义构建参数
# 传递额外的xcodebuild参数
ipa build --xcargs "OTHER_SWIFT_FLAGS=\"-DDEBUG\""
# 使用自定义xcconfig文件
ipa build --xcconfig "Configurations/Release.xcconfig"
3. 批量处理脚本
#!/bin/bash
# build_and_distribute.sh
APPS=("App1" "App2" "App3")
CONFIGURATIONS=("Debug" "Release")
for app in "${APPS[@]}"; do
for config in "${CONFIGURATIONS[@]}"; do
echo "构建 $app - $config"
ipa build --workspace "$app.xcworkspace" \
--scheme "$app" \
--configuration "$config" \
--destination "./builds/$app" \
--ipa "$app-$config.ipa"
done
done
故障排除与常见问题
1. 构建失败排查
# 启用详细输出
ipa build --verbose
# 检查Xcode版本
xcodebuild -version
# 验证项目配置
xcodebuild -list
2. 分发错误处理
# 检查网络连接
curl -I https://upload.hockeyapp.net
# 验证API令牌有效性
curl -H "X-HockeyAppToken: $HOCKEYAPP_API_TOKEN" \
https://rink.hockeyapp.net/api/2/apps
3. 证书和描述文件问题
# 列出可用签名身份
security find-identity -v -p codesigning
# 检查描述文件
security cms -D -i distribution.mobileprovision
与其他工具的集成
1. 与Fastlane协同工作
虽然Shenzhen作者推荐使用Fastlane作为现代替代方案，但Shenzhen仍然可以在特定场景下发挥作用：
# Fastlane Lane中集成Shenzhen
lane :custom_distribute do
# 使用Shenzhen进行特殊处理
sh("ipa distribute:hockeyapp --file #{lane_context[SharedValues::IPA_OUTPUT_PATH]} --notes 'Fastlane集成构建'")
end
2. Jenkins CI集成
pipeline {
agent any
stages {
stage('Build') {
steps {
sh 'gem install shenzhen'
sh 'ipa build --configuration Release'
}
}
stage('Distribute') {
steps {
sh 'ipa distribute:hockeyapp --file *.ipa --notes "Jenkins自动构建 ${env.BUILD_NUMBER}"'
}
}
}
}
最佳实践总结
- 环境隔离：为不同环境（开发、测试、生产）配置不同的构建参数
- 安全第一：使用环境变量存储敏感信息，避免硬编码
- 自动化脚本：编写可重复使用的构建和分发脚本
- 版本控制：将构建配置脚本纳入版本控制系统
- 监控日志：确保构建和分发过程的日志记录和监控
结语
Shenzhen虽然是一个相对较老的项目，但其设计理念和功能仍然值得学习。它展示了如何通过命令行工具简化iOS应用的构建和分发流程，为后来的工具如Fastlane奠定了基础。
对于需要快速搭建简单CI/CD流水线或者处理特殊分发需求的开发者来说，Shenzhen仍然是一个有价值的选择。不过对于新项目，建议考虑使用更现代的Fastlane工具套件。
无论选择哪种工具，重要的是建立自动化的构建和分发流程，让开发团队能够专注于创造价值，而不是重复的手工操作。
温馨提示：记得在使用前备份重要数据，并在测试环境中充分验证构建和分发流程！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
