如何为Composer配置HTTP Basic认证访问私有仓库？（auth.json详解）

auth.json用于Composer HTTP Basic认证，支持私有仓库访问；位置优先级为项目根目录→COMPOSER_HOME/auth.json→config.json内嵌；需精确匹配域名、避免提交至Git。

Composer 通过 auth.json 文件支持 HTTP Basic 认证，用于安全访问私有 Packagist 仓库、GitLab、GitHub（私有包）、自建 Satis/SatisPress 或其他需要用户名密码的 Composer 仓库。

auth.json 放在哪？优先级怎么算？

auth.json 可以放在多个位置，Composer 按以下顺序查找并合并（后加载的覆盖前一个同名配置）：

• 当前项目根目录下的 auth.json（最常用，适合单项目私有依赖）
• COMPOSER_HOME 环境变量指定路径下的 auth.json（默认是 ~/.composer/auth.json，全局生效）
• COMPOSER_HOME 下的 config.json 中内嵌的 http-basic 配置（不推荐，可读性差）

建议：项目级私有包用项目根目录 auth.json；团队共享仓库用全局 ~/.composer/auth.json。

auth.json 基本结构与字段说明

核心是 http-basic 键，其下每个子项对应一个仓库域名，值为含 username 和 password 的对象：

{
    "http-basic": {
        "gitlab.example.com": {
            "username": "alice",
            "password": "token_or_password_here"
        },
        "repo.mycompany.com": {
            "username": "deploy",
            "password": "abc123def456"
        }
    }
}

登录后复制

注意：
- 域名必须精确匹配仓库 URL 的 host 部分（不含协议和路径），例如 https://gitlab.example.com/api/v4/projects → 填 gitlab.example.com；
- password 可以是明文密码，但更推荐使用只读 API Token（如 GitLab Personal Access Token、GitHub Fine-grained Token），权限最小化；
- 不要将 auth.json 提交到 Git（加到 .gitignore），尤其不能出现在公开仓库中。

配合 composer.json 正确声明私有仓库

auth.json 只负责认证，还需在 composer.json 中声明仓库来源：

标签： linux word js git json composer github access mac curl ai ma