Flutter macOS 代码签名问题解决指南

问题背景

在使用 Flutter 开发 macOS 应用时，经常会遇到以下错误：

error: Signing for "Runner" requires a development team.
Select a development team in the Signing & Capabilities editor.

或者：

error: "Runner" requires a provisioning profile.
Select a provisioning profile in the Signing & Capabilities editor.

这是因为 macOS 应用默认需要代码签名才能构建和运行。本文将介绍几种解决方案及其适用场景。

解决方案对比

方案一：使用 Apple ID 签名（推荐用于正式开发）

适用场景：

  • 准备发布到 App Store 或进行 TestFlight 测试
  • 需要分发给其他开发者
  • 长期 macOS 开发

优点：

  • ✅ 最标准、最官方的做法
  • ✅ 可以使用完整的 macOS 权限和功能
  • ✅ 应用可以正常分发和安装
  • ✅ 免费 Apple ID 即可（无需付费开发者账号）

缺点：

  • ❌ 需要 Xcode（约 10-15 GB）
  • ❌ 配置相对繁琐
  • ❌ 需要网络验证

操作步骤：

  1. 安装 Xcode（从 App Store）

  2. 在 Xcode 中添加 Apple ID：

    • 打开 Xcode → Settings → Accounts
    • 点击 + 添加 Apple ID
    • 登录后会自动创建开发证书

  3. 配置项目签名：

    1

    open macos/Runner.xcworkspace
    • 选择 Runner 项目 → Runner target
    • 进入 Signing & Capabilities
    • 勾选 “Automatically manage signing”
    • 选择你的团队

  4. 构建运行：

    1

    flutter run -d macos

方案二：创建自签名证书

适用场景：

  • 不想使用 Apple ID
  • 只在自己电脑上开发测试
  • 已安装 Xcode Command Line Tools

优点：

  • ✅ 不需要 Apple ID
  • ✅ 无需网络验证
  • ✅ 支持基本的应用功能

缺点：

  • ❌ 应用无法分发给他人
  • ❌ 某些系统功能可能受限
  • ❌ 需要手动管理证书

操作步骤：

  1. 创建自签名证书：

    • 打开"钥匙串访问"（应用程序 → 实用工具）
    • 钥匙串访问 → 证书助理 → 创建证书
    • 名称：Mac Developer
    • 身份类型：自签名根证书
    • 证书类型：代码签名
    • 勾选"让我覆盖这些默认值"
    • 一路继续，最后点击创建

  2. 验证证书：

    1

    xcrun security find-identity -v -p codesigning

  3. 在 Xcode 中配置项目使用该证书（步骤同方案一）

方案三：完全禁用代码签名（推荐用于本地开发）

适用场景：

  • 纯本地开发测试
  • 不需要分发应用
  • 不想安装 Xcode
  • 快速迭代开发

优点：

  • ✅ 无需任何证书或 Apple ID
  • ✅ 无需安装 Xcode
  • ✅ 配置简单快速
  • ✅ 适合 CI/CD 环境

缺点：

  • ❌ 应用无法分发（需要用户手动处理权限）
  • ❌ 某些系统功能可能受限
  • ❌ 不符合 Apple 官方规范

操作步骤：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#!/bin/bash
FILE="macos/Runner.xcodeproj/project.pbxproj"

perl -i -pe '
  s/CODE_SIGN_ENTITLEMENTS = .*?;/CODE_SIGN_ENTITLEMENTS = "";/g;
  s/CODE_SIGN_IDENTITY = .*?;/CODE_SIGN_IDENTITY = "";/g;
  s/CODE_SIGN_STYLE = .*?;/CODE_SIGN_STYLE = Manual;/g;
  s/DEVELOPMENT_TEAM = .*?;/DEVELOPMENT_TEAM = "";/g;
  s/PROVISIONING_PROFILE_SPECIFIER = .*?;/PROVISIONING_PROFILE_SPECIFIER = "";/g;
' "$FILE"

echo "✅ Signing configuration disabled"

应用分发说明

如果选择方案三（禁用签名）进行开发，在分发应用时用户需要执行以下操作才能运行：

方法 1：移除隔离属性（推荐）

1

xattr -rd com.apple.quarantine /Applications/YourApp.app

注意：不需要使用 sudo，普通用户权限即可。

方法 2：右键打开

  1. 右键点击应用
  2. 选择"打开"
  3. 在弹出的对话框中点击"打开"

这种方法可以绕过 Gatekeeper 的检查，但只需要操作一次。

推荐方案总结

场景推荐方案理由
本地快速开发方案三（禁用签名）配置简单，开发效率高
团队协作开发方案一（Apple ID）标准流程，便于协作
准备发布应用方案一（Apple ID）必须使用正式签名
无 Xcode 环境方案三（禁用签名）不依赖 Xcode
CI/CD 自动化方案三（禁用签名）减少外部依赖

常见问题

Q: 为什么会出现 “0 valid identities found”？

A: 这表示系统中没有可用的代码签名证书。可以选择：

  1. 在 Xcode 中登录 Apple ID 自动创建
  2. 手动创建自签名证书
  3. 完全禁用签名（方案三）

Q: entitlements 文件的作用是什么？

A: entitlements 文件定义了应用的权限，例如：

  • app-sandbox: 是否启用沙盒
  • allow-jit: 是否允许 JIT 编译（Flutter 需要）
  • network.client/server: 网络访问权限

Q: 禁用签名后应用安全吗？

A: 对于本地开发完全安全。但分发给用户时：

  • 用户需要手动信任应用
  • 系统会显示"来自身份不明开发者"的警告
  • 不适合公开分发

Q: 如何在开发和发布之间切换？

A:

  • 开发时使用方案三（禁用签名）
  • 发布前切换到方案一（Apple ID 签名）
  • 可以通过 Git 管理不同配置

结论

对于日常开发，方案三（完全禁用签名） 是最高效的选择，无需额外工具，配置简单。当需要正式发布时，再切换到方案一（Apple ID 签名）。

选择合适的方案可以大大提升开发效率，避免在签名问题上浪费时间。

参考资源：