使用auth.json可安全管理Composer私有仓库认证。1. 创建GitLab等服务的访问令牌；2. 在composer.json中配置私有仓库地址；3. 在项目根目录创建auth.json文件存储凭证，避免提交至版本控制；4. 推荐提供auth.json.dist模板并结合CI/CD环境变量注入密钥，提升团队协作安全性与效率。
在使用 Composer 管理 PHP 项目依赖时，经常会遇到需要访问私有仓库（如私有 Packagist、GitHub、GitLab 或 Nexus）的情况。这些仓库通常需要身份验证，直接把 token 或用户名密码写在 composer.json 中不仅不安全，还容易被提交到版本控制系统中造成泄露。
更优雅的方式是使用 auth.json 文件来集中管理认证信息，既保证安全性，又便于团队协作和环境隔离。
什么是 auth.json？
auth.json 是 Composer 提供的一个专门用于存放敏感认证数据的配置文件。它与 composer.json 同级或位于 Composer 的全局配置目录中，不会被意外暴露在项目代码里。
该文件支持以下几种认证方式：
- http-basic：用于 HTTP 基本身份验证（如私有 Git 仓库）
- github-oauth：用于 GitHub 的 Personal Access Token
- gitlab-token：用于 GitLab 的私人令牌
- bitbucket-oauth：用于 Bitbucket 的 OAuth 令牌
如何使用 auth.json 配置私有仓库认证
假设你有一个私有 Composer 包托管在 GitLab 私有仓库中，你需要让 Composer 能够拉取这个包。
步骤 1：准备你的访问令牌
前往 GitLab → Settings → Access Tokens，创建一个具有 read_repository 权限的 token。
步骤 2：配置 composer.json 添加仓库源
确保你的 composer.json 中已注册私有仓库：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.com/your-company/your-private-package.git"
}
]
}
步骤 3：创建 auth.json 文件
在项目根目录下创建 auth.json（此文件应加入 .gitignore）：
{
"http-basic": {
"gitlab.com": {
"username": "oauth2",
"password": "glpat-xXXXXXXX"
}
}
}
注意：GitLab 使用 oauth2 作为用户名，token 作为密码。
步骤 4：运行 Composer 安装命令
执行 composer install，Composer 会自动读取 auth.json 中的凭证完成认证。
推荐的部署与团队协作实践
为了兼顾安全性和可维护性，建议采用以下策略：
- 将
auth.json加入项目的.gitignore，避免误提交 - 提供
auth.json.dist作为模板，例如：{ "http-basic": { "gitlab.com": { "username": "oauth2", "password": "your-gitlab-token-here" } } } - 在 CI/CD 环境中通过环境变量注入 token，例如 GitHub Actions 中使用 secrets：
- name: Set up auth.json run: | mkdir -p ~/.composer echo '{"http-basic": {"gitlab.com": {"username": "oauth2", "password": "${{ secrets.GITLAB_TOKEN }}"}}}' > ~/.composer/auth.json - 也可使用 Composer 命令行设置全局凭证：
composer config --global http-basic.gitlab.com oauth2 glpat-xXXXXXXX这会在全局auth.json（通常是~/.composer/auth.json）中保存凭据
安全注意事项
尽管 auth.json 提供了更好的组织方式，但仍需注意：
- 永远不要将包含真实 token 的
auth.json提交到 Git - 定期轮换访问令牌，尤其是离职人员曾接触过的 token
- 为 token 设置最小必要权限（如只读）
- 在共享开发环境中慎用全局配置
基本上就这些。通过 auth.json 分离敏感信息，不仅能提升项目安全性，也让依赖管理更清晰可控。合理使用模板与自动化配置，还能显著提升团队协作效率。不复杂但容易忽略。
