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

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

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

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

"repositories": [
    {
        "type": "vcs",
        "url": "https://gitlab.example.com/group/private-package.git"
    }
]

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

调试与常见问题

如果认证失败（报错如 401 Unauthorized 或 Failed to download ... Invalid credentials），按顺序检查：

运行 composer config --global --list | grep -i auth 查看是否误配了全局凭据
确认 auth.json 文件权限：避免被其他用户读取（Linux/macOS 上建议 chmod 600 auth.json）
用 curl -v -u user:pass https://repo.example.com/packages.json 手动测试是否能通
注意某些 Git 服务商（如 GitLab）要求 token 放在 username 字段、密码留空，或反向（取决于 API 版本），查阅对应文档

另外，Composer 2.2+ 支持 auth.json 加密（需配合 composer config --auth 命令），但日常开发中明文 + 合理权限控制已足够安全。

基本上就这些。auth.json 是 Composer 访问私有生态的钥匙，结构简单，但域名匹配和文件位置容易出错，配好一次，后续 install/update 就能自动走认证流程。

# linux # word # js # git # json # composer # github # access # mac # curl # ai

相关栏目：【网站优化151355 】【网络推广146373 】【网络技术251813 】【 AI营销90571 】