如何在 Composer 中配置认证信息（auth.json）以下载私有包？-composer-PHP中文网

如何在 Composer 中配置认证信息（auth.json）以下载私有包？

穿越時空

发布： 2025-12-23 14:13:02

原创

630人浏览过

Composer 下载私有包需通过 auth.json 配置认证凭据，支持全局（~/.composer/auth.json）或项目级路径，格式含 http-basic、github-oauth、gitlab-token 等字段，须按平台选用对应 token 并注意权限与安全实践。

如何在 composer 中配置认证信息（auth.json）以下载私有包？

在 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：

MimicPC

一个AI驱动的浏览器运行工具，可以通过浏览器在线安装及运行各种开源的AI应用程序

145

查看详情

项目级 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