auth.json未被正确加载是401错误主因；需用composer config --global命令生成、确保路径正确（项目根目录或~/.composer/）、权限600、UTF-8无BOM编码、域名端口完全匹配，并通过composer diagnose和composer show -a验证生效。
在使用 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 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"}}}'，该变量优先级最高，覆盖所有文件配置。
验证认证是否真正起作用
执行 composer diagnose，观察输出中是否有 “Authentication configured” 提示；没有则说明凭据仍未加载。
再运行 composer show -a vendor/private-package，如果返回包信息而非 401，说明认证链已通。
最后执行 composer install，此时应能正常拉取私有包，不再卡在 “Auth required” 或静默失败。
