fastlane CredentialsManager 详解：Apple 开发者账号的凭证存储、Keychain 管理与环境变量配置

fastlane 工具链中绝大多数组件（deliver、gym、sigh、spaceship 等）都需要 Apple 开发者账号的用户名与密码。credentials_manager 是 fastlane 仓库中专门负责这块的独立模块：它定义了凭据的获取顺序、macOS Keychain 的存取方式、命令行增删命令，以及供第三方集成的 Ruby API。读完本文，你将掌握 fastlane-credentials 命令的完整用法、FASTLANE_USER / FASTLANE_PASSWORD 等环境变量的优先级逻辑，并能基于 CredentialsManager::AccountManager 自行实现一套认证方案。

一、CredentialsManager 的定位与目录结构

credentials_manager 是 fastlane 工具链中被引用最多的组件之一，所有与“用户名/密码”相关的代码都集中在这里。整个模块非常精简，只有三个核心文件（见 credentials_manager/lib/credentials_manager.rb）：

文件	职责
account_manager.rb	核心类 AccountManager：凭据获取顺序、Keychain 读写、交互式登录提示
cli.rb	fastlane fastlane-credentials 命令行的 add / remove 子命令实现
appfile_config.rb	解析项目中的 Appfile，为 apple_id 提供文件级回退值

该模块被 fastlane 主程序分发的入口 fastlane/lib/fastlane/cli_tools_distributor.rb 接入：当执行 fastlane fastlane-credentials ... 时，程序 require 'credentials_manager' 后直接启动 CredentialsManager::CLI.new.run，无需进入 lane 执行流程。

二、命令行用法：fastlane-credentials add / remove

除了 Ruby 库，fastlane 提供命令行界面直接向 Keychain 添加或删除凭据。命令解析逻辑位于 credentials_manager/lib/credentials_manager/cli.rb，程序名为 CredentialsManager，全局支持 --env 选项（用于加载 dotenv 环境变量）。

添加凭据，支持 --username 与 --password 两个选项；若省略会交互式询问（密码输入时以 * 掩码回显，来自 Highline）：

fastlane fastlane-credentials add --username [e-mail]
Password: *********
Credential [e-mail]:********* added to keychain.

删除凭据，只需 --username：

fastlane fastlane-credentials remove --username [e-mail]
password has been deleted.

从源码看，add 子命令最终调用的是 AccountManager#add_to_keychain，remove 子命令调用 AccountManager#remove_from_keychain（见 cli.rb 的 add/remove 私有方法），也就是说 CLI 只是 AccountManager 的一个薄封装。

三、凭据获取顺序：AccountManager 的解析链

AccountManager（credentials_manager/lib/credentials_manager/account_manager.rb）是整个模块的心脏。理解它的 user 与 password 两个方法，就理解了 fastlane 所有工具“从哪里读到账号密码”。

3.1 用户名的解析顺序

AccountManager#user（L30-L39）在默认前缀（deliver）下依次尝试：

1. ENV["FASTLANE_USER"]
2. ENV["DELIVER_USER"]（deliver 工具的历史遗留变量）
3. AppfileConfig.try_fetch_value(:apple_id) —— 即项目 Appfile 中的 apple_id 字段
4. 以上都取不到时，交互式提示输入 Username；若运行在非交互 shell（$stdout.isatty == false）则直接抛出 Missing username, and running in non-interactive shell 异常

Appfile 侧的回退逻辑在 appfile_config.rb：Appfile 找不到 apple_id 时还会继续回退到 FASTLANE_USER → DELIVER_USER → DELIVER_USERNAME 环境变量。Appfile 的默认搜索路径为 ./fastlane/Appfile、./.fastlane/Appfile、./Appfile 三个位置（L18-L23）。

3.2 密码的解析顺序

AccountManager#password（L47-L58）的顺序为：

1. fetch_password_from_env：ENV["FASTLANE_PASSWORD"] → ENV["DELIVER_PASSWORD"]（仅默认前缀时生效，且空字符串视为未提供）
2. macOS Keychain 中的 Internet Password 条目（通过 Security::InternetPassword.find(server: server_name) 查找）
3. 交互式提示输入密码（掩码回显）

一个值得注意的细节：如果环境变量中的 FASTLANE_PASSWORD 被设置为空字符串，系统不会采用它，而是继续从 Keychain 读取——这一点由测试用例 loads the password from the keychain if empty password is stored by env 明确验证（见 credentials_manager/spec/account_manager_spec.rb）。

3.3 凭据错误时的处理：invalid_credentials

AccountManager#invalid_credentials（L63-L79）用于登录失败后的重试场景：

• 若密码来自环境变量，只提示“请确认环境变量中的密码正确”，不删除 Keychain 条目，返回 false；
• 否则询问用户是否重新输入密码（force: true 可跳过询问），用户同意后删除 Keychain 条目并重新交互式登录。

该方法的真实调用方包括 fastlane_core/lib/fastlane_core/itunes_transporter.rb 与 match/lib/match/spaceship_ensure.rb。

四、Keychain 存储：条目命名、前缀机制与手动改密

4.1 条目命名与前缀

fastlane 使用 macOS Keychain 的 Internet Password 类型存储 Apple 密码，条目名由 server_name 方法生成：

def server_name
  "#{@prefix}.#{user}"
end

默认前缀为 deliver（DEFAULT_PREFIX = "deliver"，L8），因此为 [e-mail] 存储的条目名为 [e-mail]——这一命名在测试中被明确断言（account_manager_spec.rb 中 Security::InternetPassword.find(server: "[e-mail]")）。

prefix 参数允许自定义前缀：当使用非 deliver 前缀时，工具会跳过环境变量与 Appfile，只从 Keychain 取对应条目（user / password 方法均以 default_prefix? 为条件）。源码注释说明这一机制用于 iTunes Transporter 的应用专用密码（application specific password）——它需要与主账号密码分开存储。AccountManager.new(user:, password:, prefix:, note:) 还支持 note 参数，会在登录提示语中显示补充说明（如“请使用应用专用密码”）。

4.2 存储时的附加字段

options 方法（L100-L106）会把 FASTLANE_PATH / FASTLANE_PORT / FASTLANE_PROTOCOL 三个环境变量作为附加字段（:p / :P / :r）写入 Keychain 条目。源码注释表明这些变量用于 Xamarin Studio 认证 Apple 开发者账号的兼容场景；三个变量都未设置时 options 返回 nil，即不写入附加字段。

4.3 手动修改/删除已存密码

默认情况下 Apple 凭据只保存在你本机的 macOS Keychain 中，密码不会离开你的电脑。要修改已存的密码，官方推荐的手动流程是：

1. 打开 macOS 的 “钥匙串访问”（Keychain Access） 应用；
2. 切换到 All Items，搜索 deliver；
3. 选中要修改的条目并删除；
4. 下次运行任一 fastlane 工具时会被要求输入新密码，新密码将自动写回 Keychain。

删除失败或不想交互时，也可以用命令行 fastlane fastlane-credentials remove --username <用户名> 完成同样的事。

五、环境变量全览

除 README 提到的 FASTLANE_USER / FASTLANE_PASSWORD / FASTLANE_DONT_STORE_PASSWORD 外，源码中还涉及若干相关变量，完整清单如下（均可在 account_manager.rb 与 appfile_config.rb 中确认）：

环境变量	作用	生效位置
FASTLANE_USER	提供用户名，优先级最高	AccountManager#user、AppfileConfig#fallback_to_default_values
FASTLANE_PASSWORD	提供密码；设置后不再交互询问密码	AccountManager#fetch_password_from_env
FASTLANE_DONT_STORE_PASSWORD	设为 "1" 后，交互输入的密码不写入 Keychain（L140）	非 macOS 环境同样不会存储（return true unless mac?）
DELIVER_USER / DELIVER_PASSWORD / DELIVER_USERNAME	deliver 工具的历史遗留变量，作为 FASTLANE_* 的回退	#user / #fetch_password_from_env / Appfile 回退
FASTLANE_HIDE_LOGIN_INFORMATION	设为任意非空值时，隐藏登录横幅提示（L111-L122）	适合 CI 日志等不希望输出品牌横幅的场景
FASTLANE_PATH / FASTLANE_PORT / FASTLANE_PROTOCOL	写入 Keychain 条目的附加字段（Xamarin 认证兼容）	#options

典型 CI 用法即通过前两个变量免交互完成认证；FASTLANE_DONT_STORE_PASSWORD=1 则保证 CI 机器上不落盘任何密码。

六、Appfile 回退：for_lane 与 for_platform

AppfileConfig（credentials_manager/lib/credentials_manager/appfile_config.rb）负责读取 Appfile 内容，除了为 apple_id 提供默认值，还提供两套按上下文覆盖配置的能力，它们会影响哪些账号被解析出来：

• for_lane(lane_name)（L160-L174）：仅当 ENV["FASTLANE_LANE_NAME"] 等于给定 lane 名时执行块内配置，适合为 beta / enterprise 等 lane 指定不同账号；
• for_platform(platform_name)（L183-L187）：仅当 ENV["FASTLANE_PLATFORM_NAME"] 匹配时生效。

两个值得留意的实现细节：

1. 每次读取都重新加载文件：try_fetch_value 的注释说明这是为了支持 for_lane——一次 fastlane 运行中值可能随 lane 切换而变化；
2. 智能引号清洗：加载时若检测到弯引号（“ ” ‘ ’ ‛），会就地替换为直引号并输出红色警告，提示不要用 TextEdit 编辑 Appfile。测试 fixture credentials_manager/spec/fixtures/Appfile_smart_quotes 专门验证了这种情况仍能正确解析。

for_lane / for_platform 的各种组合行为（平台 + lane 覆盖、同名 lane 不同平台、无匹配时回退默认值等）都有系统化的测试覆盖，见 credentials_manager/spec/app_file_config_spec.rb 及 fixtures 目录下的 Appfile1～Appfile10 系列样例文件。

七、用 Ruby 库实现自定义认证方案

所有 fastlane 工具都是 Ruby 编写的，credentials_manager 可以直接作为库 require，实现自己的认证逻辑（README 中的最小示例）：

require 'credentials_manager'

data = CredentialsManager::AccountManager.new(user: user, password: password)
puts data.user
puts data.password

构造函数完整签名为 initialize(user: nil, password: nil, prefix: nil, note: nil)。传入自定义 prefix 后，凭据会存到 prefix.用户名 命名的独立 Keychain 条目中，且不再走环境变量/Appfile 回退链——这正是工具区分“主账号密码”和“应用专用密码”的手段。

fastlane 仓库内的真实调用链可以印证这一设计：

• spaceship/lib/spaceship/client.rb 用 AccountManager.new(user:, password:) 登录后 add_to_keychain，后续会话直接凭 Keychain 条目免输入；
• fastlane_core/lib/fastlane_core/itunes_transporter.rb 用非默认前缀的 AccountManager 处理应用专用密码，并在认证失败时调用 invalid_credentials 引导用户重输；
• fastlane 内置动作 register_device / register_devices 用 AccountManager.new(user: params[:username]) 读取指定用户的凭据。

八、测试如何固化这些行为

credentials_manager 模块的单元测试对本文所有关键结论提供了直接证据（credentials_manager/spec/account_manager_spec.rb）：

• FASTLANE_USER / FASTLANE_PASSWORD 可独立注入用户名与密码；
• 遗留的 DELIVER_USER / DELIVER_PASSWORD 仍然受支持；
• Appfile fixture（credentials_manager/spec/fixtures/Appfile 中 apple_id "[e-mail]"）验证了“从 Appfile 读取 Apple ID”；
• Keychain 条目名断言为 [e-mail]，且支持自定义前缀 #{prefix}.#{user}；
• invalid_credentials(force: true) 会触发 Security::InternetPassword.delete(server: "[e-mail]")。

九、小结

credentials_manager 用不到 500 行 Ruby 代码，为整个 fastlane 工具链提供了一致的凭据管理基线：

1. 解析链有明确优先级：环境变量 > Appfile > Keychain > 交互提示，且每一步都有对应的测试用例兜底；
2. Keychain 是默认且唯一的本地存储，条目名为 deliver.用户名（前缀可定制），可通过钥匙串访问应用或 fastlane fastlane-credentials remove 手动管理；
3. CI 场景用 FASTLANE_USER / FASTLANE_PASSWORD 免交互，FASTLANE_DONT_STORE_PASSWORD=1 避免落盘；
4. 扩展场景（如应用专用密码、多账号）通过 prefix / note 参数与 Appfile 的 for_lane / for_platform 组合实现，第三方 Ruby 项目可直接 require 'credentials_manager' 复用整套逻辑。

模块声明其代码受 MIT 许可证保护，且所有工具仅运行在你自己的电脑或服务器上，凭据等敏感信息不会离开本机——这一隐私边界由源码中“本地 Keychain + 本地进程内 env”的实现方式直接保证。