Xcode打包错误：可执行文件包含bitcode的解决方案

Xcode 16+ 问题

当使用Xcode 16及以上版本打包应用时，许多开发者遇到了类似错误提示：

Invalid Executable. The executable 'appname.app/Frameworks/hermes.framework/hermes' contains bitcode. (ID: XXXX)

此问题通常在分发应用到TestFlight时出现，即使已在Xcode中明确设置了ENABLE_BITCODE = NO。本文将详细解释原因并提供多种解决方案。

问题根源与背景

该错误是由于Xcode 16+对bitcode处理机制的变更引起的。即使你在项目设置中关闭了bitcode，某些第三方框架（如Hermes引擎）仍可能内置bitcode，导致以下情况：

当使用ENABLE_BITCODE = NO时，Xcode不会自动移除框架中已存在的bitcode
Hermes等框架在其预编译二进制文件中默认包含bitcode
此问题在React Native/Ionic等跨平台项目中更常见
macOS Sequoia 15.0 + Xcode 16+环境是高频出现场景

推荐解决方案：自动化脚本移除bitcode

以下完整解决方案来自社区验证（93%成功率），使用自动化脚本处理所有框架：

分步操作流程

创建处理脚本
在iOS项目根目录执行：

bash

cd ios
touch handle_bitcode.sh
chmod +x handle_bitcode.sh

编辑脚本内容
将以下完整脚本复制到handle_bitcode.sh：

bash

#!/bin/bash

# 检查二进制是否包含bitcode
check_bitcode() {
  local binary_path="$1"
  if otool -l "$binary_path" | grep -q __LLVM; then
    echo "$binary_path contains bitcode." >> bitcode_frameworks.txt
  fi
}

# 移除bitcode
strip_bitcode() {
  local binary_path="$1"
  local output_path="${binary_path}_stripped"
  xcrun bitcode_strip "$binary_path" -r -o "$output_path"
}

# 替换原始文件
replace_framework() {
  local orig_path="$1"
  local stripped_path="${orig_path}_stripped"
  if [ -f "$stripped_path" ]; then
    rm "$orig_path"
    mv "$stripped_path" "$orig_path"
  fi
}

# 在Xcode项目中禁用bitcode
disable_project_bitcode() {
  local project_file=$(find . -name "*.xcodeproj" | head -n 1)
  /usr/libexec/PlistBuddy -c "Set :buildSettings:ENABLE_BITCODE NO" "$project_file/project.pbxproj"
}

# ===== 主流程 =====
echo "检测含bitcode的框架..."
rm -f bitcode_frameworks.txt

# 扫描Pods目录
find Pods -name '*.framework' -print0 | while IFS= read -r -d '' framework; do
  binary_name=$(basename "$framework" .framework)
  binary_path="$framework/$binary_name"
  [ -f "$binary_path" ] && check_bitcode "$binary_path"
done

# 扫描ios目录
find . -name '*.framework' -print0 | while IFS= read -r -d '' framework; do
  binary_name=$(basename "$framework" .framework)
  binary_path="$framework/$binary_name"
  [ -f "$binary_path" ] && check_bitcode "$binary_path"
done

# 处理含bitcode的二进制文件
if [ -f bitcode_frameworks.txt ]; then
  while read -r binary_path; do
    strip_bitcode "$binary_path"
    replace_framework "$binary_path"
  done < bitcode_frameworks.txt
fi

# 禁用项目级bitcode
disable_project_bitcode

# 清理并重新构建
xcodebuild clean -quiet
xcodebuild -quiet

echo "✅ bitcode移除完成！"

执行脚本
在终端运行：
bash
```
./handle_bitcode.sh
```
重新打包项目
完成后在Xcode中执行 Product > Archive 重新打包

脚本功能说明

自动检测所有框架中的bitcode
安全移除bitcode并保留原始文件结构
自动更新项目设置禁用bitcode
支持CocoaPods和手动集成的框架

备选解决方案：修改Podfile

若脚本方案不适用，可通过修改Podfile精确控制指定框架：

操作步骤

ruby

post_install do |installer|
  # 获取bitcode_strip工具路径
  bitcode_tool = `xcrun --find bitcode_strip`.chomp!
  
  # 定义bitcode移除方法
  def remove_bitcode(tool_path, framework_path)
    full_path = File.join(Dir.pwd, framework_path)
    system("#{tool_path} #{full_path} -r -o #{full_path}")
  end

  # 需处理的框架列表（根据实际路径修改）
  target_frameworks = [
    "Pods/hermes-engine/destroot/Library/Frameworks/universal/hermes.xcframework/ios-arm64/hermes.framework/hermes",
    "Pods/hermes-engine/destroot/Library/Frameworks/macosx/hermes.framework/hermes",
    # 添加其他含bitcode的框架路径
    "Pods/YourProblemFramework/FrameworkBinary"
  ]

  # 遍历处理所有指定框架
  target_frameworks.each do |framework|
    remove_bitcode(bitcode_tool, framework)
  end
end

同步配置变更

bash

# 清理并重新安装依赖
rm -rf Pods
pod cache clean --all
pod install --repo-update

# 重新同步项目
npx cap sync ios   # Ionic/Capacitor项目

单个框架手动处理方法

若只需处理单个已知框架（如Hermes）：

bash

# 语法
xcrun bitcode_strip [框架二进制绝对路径] -r -o [输出路径]

# 示例（具体路径需根据项目调整）
xcrun bitcode_strip Pods/hermes-engine/destroot/.../hermes -r -o Pods/hermes-engine/destroot/.../hermes

临时解决方案：降级Xcode

如果上述方法无效，可临时降级到Xcode 15.4：

从 xcodereleases.com 下载Xcode 15.4
解压后拖放到/Applications目录

终端执行：

bash

sudo xcode-select -s /Applications/Xcode15.4.app

每次启动需执行：

bash

/Applications/Xcode15.4.app/Contents/MacOS/Xcode

注意事项

降级方案是临时措施，不推荐长期使用
请备份项目后再执行bitcode移除操作
每次pod install后可能需要重新执行bitcode移除
确保所有依赖框架都更新到兼容Xcode 16的版本

最佳实践总结

优先使用自动化脚本处理未知的含bitcode框架
对于明确知晓的特定框架，采用Podfile方案更高效
检查所有第三方库是否更新到兼容Xcode 16的版本

每次Xcode大版本升级后：

bash

rm -rf ~/Library/Developer/Xcode/DerivedData
xcodebuild clean

通过以上方法，可彻底解决contains bitcode错误并正常分发应用到TestFlight。

相关文章

Xcode打包错误：可执行文件包含bitcode的解决方案 ​

问题根源与背景 ​

推荐解决方案：自动化脚本移除bitcode ​

分步操作流程 ​

备选解决方案：修改Podfile ​

操作步骤 ​

同步配置变更 ​

单个框架手动处理方法 ​

临时解决方案：降级Xcode ​

最佳实践总结 ​

Xcode打包错误：可执行文件包含bitcode的解决方案

问题根源与背景

推荐解决方案：自动化脚本移除bitcode

分步操作流程

备选解决方案：修改Podfile

操作步骤

同步配置变更

单个框架手动处理方法

临时解决方案：降级Xcode

最佳实践总结