Composer 下载私有包需通过 auth.json 配置认证凭据，支持全局（~/.composer/auth.json）或项目级路径，格式含 http-basic、github-oauth、gitlab-token 等字段，须按平台选用对应 token 并注意权限与安全实践。
在 Composer 中下载私有包（如 GitHub、GitLab 或私有 Packagist）时，需要通过 auth.json 提供认证凭据。这个文件告诉 Composer 如何登录远程服务，从而拉取受保护的代码库。
auth.json 文件的位置和格式
auth.json 默认放在两个位置之一：
– 全局：用户主目录下的 COMPOSER_HOME（通常是 ~/.composer/auth.json 或 ~/Library/Application Support/Composer/auth.json（macOS）、%APPDATA%\Composer\auth.json（Windows））
– 项目级：当前项目的根目录下（与 composer.json 同级），仅对该项目生效
内容是标准 JSON，结构如下：
{
"http-basic": {
"your-private-packagist.com": {
"username": "your-username",
"password": "your-api-token-or-password"
}
},
"github-oauth": {
"github.com": "your-personal-access-token"
},
"gitlab-token": {
"gitlab.example.com": "your-gitlab-personal-token"
}
}
为不同平台配置对应认证方式
不同服务支持的认证机制不同，需按平台选择字段：
-
GitHub 私有仓库：用
github-oauth，值为 Personal Access Token（建议勾选repo权限） -
GitLab 私有仓库或实例：用
gitlab-token，值为 Personal Access Token（需read_repository权限） -
私有 Packagist / Satis / Toran Proxy：用
http-basic，填入域名 + 用户名/密码或 API token（很多私有仓库把 token 当作密码使用） -
Bitbucket Server（自托管）：也走
http-basic，用户名为 Bitbucket 账号，密码为 App Password（非登录密码）
安全注意事项和最佳实践
auth.json 包含敏感信息，务必避免提交到 Git：
- 项目级
auth.json应加入.gitignore - 全局
auth.json由 Composer 自动管理，权限应设为600（仅属主可读写）：chmod 600 ~/.composer/auth.json - CI/CD 环境中，推荐用环境变量注入（如 GitHub Actions 的
secrets），再在运行时生成auth.json，而不是硬编码或挂载明文文件 - Token 应最小权限原则，定期轮换，不用时及时撤销
验证和调试方法
配置完后，可通过以下方式确认是否生效：
- 运行
composer config --global --list | grep auth查看全局配置摘要 - 执行
composer diagnose，它会检查auth.json是否可读、格式是否合法 - 尝试安装一个私有包：
composer require vendor/private-package，失败时注意错误提示（如401 Unauthorized通常表示凭证无效或过期） - 加
-v参数查看详细请求过程：composer install -v
基本上就这些。配置本身不复杂，但容易忽略权限、作用域和 token 类型匹配的问题。对准平台文档生成对应 token，再按字段填进 auth.json，就能稳定拉取私有包了。
