Composer仓库配置中auth.json认证使用教程-composer-PHP中文网

auth.json未被正确加载是401错误主因；需用composer config --global命令生成、确保路径正确（项目根目录或~/.composer/）、权限600、utf-8无bom编码、域名端口完全匹配，并通过composer diagnose和composer show -a验证生效。

composer仓库配置中auth.json认证使用教程

在使用 Composer 安装私有 GitLab、Packagist 或自建仓库的包时，遇到 “Could not authenticate” 或 401 错误，90% 的情况不是 Token 无效，而是 auth.json 没被正确加载——Composer 会静默跳过错误配置，不提示、不报路径错、也不验证格式，直到请求发出才返回 401。

确认 auth.json 是否生效

运行以下命令检查全局凭据是否已注册：

【composer config --global --list | grep -E "(http-basic|github-oauth|gitlab-token|bearer)"】

如果输出为空，说明凭据根本没写入或未被识别；此时不要急着改文件，先用 composer config 命令生成。

执行 composer config --global http-basic.gitlab.example.com deploy-user abc123xyz，它会自动创建 ~/.composer/auth.json 并写入标准结构，避免手动编辑漏括号、引号或逗号。

auth.json 放在哪才被读取

Composer 按固定顺序查找 auth.json：

① 当前项目根目录（与 composer.json 同级）→ ② COMPOSER_HOME 目录（Linux/macOS 是 ~/.composer/，Windows 是 %APPDATA%\Composer\）→ ③ 系统级配置目录（极少用）。

项目级 auth.json 必须和 composer.json 在同一层，不能放在 vendor/、src/ 或子目录里；一旦放错，Composer 完全无视。

【Linux/macOS 下必须运行 chmod 600 ~/.composer/auth.json】，否则 Composer 直接跳过该文件——这是最常被忽略的权限陷阱。

用 file -i ~/.composer/auth.json 检查编码，必须是 charset=utf-8；若显示 utf-8-with-bom 或 us-ascii，用 VS Code 以 UTF-8 无 BOM 重新保存。

auth.json 手动编写格式规范

方法一：HTTP 基础认证（适用于私有 Packagist、GitLab HTTP 认证页）

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

域名必须完全匹配仓库 URL 中的 host:port 部分。例如仓库地址是 https://gitlab.internal:8080/myorg/pkg.git，则 key 必须写成 "gitlab.internal:8080"，少端口或加 https:// 都会失败。

方法二：Bearer Token（适用于支持 Bearer 头的私有源）

结构为 {"bearer": {"myrepo.example.com": "token_abc123"}}，注意 key 名是域名，不是 URL 路径，且 token 值为纯字符串，不加 "Bearer " 前缀。

方法三：GitLab OAuth Token（仅限 GitLab 实例）

命令行写入更安全：composer config --global gitlab-oauth.gitlab.example.com your_personal_access_token。手动写时 key 固定为 "gitlab.example.com"，不是 "gitlab.com"——即使你用的是 GitLab Enterprise，也必须按实际域名写。

项目级 vs 全局 auth.json 的选择

开发阶段调试私有包时，优先用项目级 auth.json：直接在项目根目录新建 auth.json，内容只写当前仓库所需凭据，不用影响其他项目。

务必把项目级 auth.json 加入 .gitignore，否则明文密码会被提交到 Git 历史——这是不可逆的安全事故。

CI/CD 流水线中禁止放任何 auth.json 文件，必须通过环境变量注入：COMPOSER_AUTH='{"http-basic":{"gitlab.example.com":{"username":"$USER","password":"$TOKEN"}}}'，该变量优先级最高，覆盖所有文件配置。