商业组件授权密钥不可手动复制粘贴分发，必须通过auth.json等机制实现凭据与代码分离；严禁写入composer.json或提交至Git，否则导致历史泄露、CI日志暴露及协作断裂；应利用环境隔离、加密secrets动态生成auth.json，并严格校验域名与权限范围。
商业组件的授权秘钥不能靠手动复制粘贴分发，否则必然在团队协作、CI/CD 和多环境部署中出问题。 Composer 本身不提供秘钥托管能力，但可以通过组合 auth.json、私有仓库配置和环境隔离机制，把秘钥作为“认证凭据”而非“代码资产”来管理——这才是可落地的简化路径。
为什么不能把秘钥写进 composer.json 或提交到 Git
这是最常踩的坑：有人把 "token": "xxx" 直接塞进 repositories 配置里，甚至提交到仓库。后果很直接：
- Git 历史永久泄露秘钥，撤回成本极高
- CI 环境（如 GitHub Actions）若未严格屏蔽敏感变量，
composer install会直接暴露 token 到日志 - 开发同事 clone 后无法直接安装，要么删配置、要么填自己 token，协作链路断裂
正确做法是让 Composer 从本地或环境可信位置读取凭据，且不参与版本控制。
用 auth.json 实现用户级凭据隔离
auth.json 是 Composer 官方支持的凭据文件，优先级高于 composer.json 中的内联配置，且默认不被 Git 跟踪（应加入 .gitignore）。
它有两种生效范围：
- 项目级：
./auth.json（仅对当前项目生效，适合临时调试） - 全局级：
~/.composer/auth.json（对所有项目生效，适合个人开发环境）
示例内容（用于访问私有 Packagist 或付费组件仓库）：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
{
"http-basic": {
"packages.example.com": {
"username": "your-license-email@example.com",
"password": "your-actual-api-token"
}
}
}
注意：password 字段实际承载的是 token，不是密码；某些商业组件（如 Laravel Nova）要求用邮箱作 username，token 作 password，顺序不能颠倒。
CI/CD 中安全注入秘钥的实操要点
GitHub Actions、GitLab CI 等平台不支持直接写入 ~/.composer/auth.json，需在 job 中动态生成。关键点在于：
- 使用平台提供的加密 secrets（如
SECRET_NOVA_TOKEN），绝不在脚本中echo $TOKEN或记录日志 - 生成
auth.json后立即执行composer install，避免文件残留 - 确认私有仓库域名与
auth.json中的 key 严格一致（含端口、协议前缀都不行）
GitHub Actions 示例片段：
- name: Set up auth.json
run: |
mkdir -p ~/.composer
cat > ~/.composer/auth.json <<EOF
{
"http-basic": {
"nova.laravel.com": {
"username": "${{ secrets.NOVA_EMAIL }}",
"password": "${{ secrets.NOVA_TOKEN }}"
}
}
}
EOF
- name: Install dependencies
run: composer install --no-interaction
多个商业组件共存时的域名冲突处理
当同时使用 Nova、Spark、Pest 商业版等，它们可能都托管在 https://nova.laravel.com、https://spark.laravel.com 这类独立域名下——这时 auth.json 的 key 就是域名本身，不存在冲突。
但若多个组件打包在同一个私有仓库（如自建 Satis 或 Private Packagist），而你又为不同客户分配了不同 token，则必须：
- 确保每个客户环境使用专属
auth.json - 避免复用同一份
composer.lock文件跨客户部署（lock 文件会固化 repo 地址和 hash，但不固化凭据） - 在
composer install前校验auth.json是否存在且可读，否则失败比静默跳过更安全
真正难的不是加几行 JSON，而是让整个流程不依赖人工干预、不留下凭据痕迹、不因环境差异突然中断 —— 这些细节漏掉一个，授权管理就又变回手工活。
