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

技术教程
2025-12-16 19:33:12

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

如何为composer配置http basic认证访问私有仓库？（auth.json详解）

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 中声明仓库来源：

QoQo

QoQo是一款专注于UX设计的AI工具，可以帮助UX设计师生成用户角色卡片、用户旅程图、用户访谈问卷等。

172 查看详情 QoQo

如果是私有 Packagist 兼容仓库（如 Satis、Private Packagist），添加 repositories：

"repositories": [
    {
        "type": "composer",
        "url": "https://repo.mycompany.com"
    }
]

如果是 Git 仓库（GitHub/GitLab 私有库），可直接写 VCS 类型，Composer 会自动识别 host 并查 auth.json：

<pre class="brush:php;toolbar:false;">"repositories": [
    {
        "type": "vcs",
        "url": "https://gitlab.example.com/group/private-package.git"
    }
]

只要 auth.json 中存在 <code>"gitlab.example.com" 条目，Composer 在克隆或获取元数据时就会自动带上 Basic Auth 头。