composer 通过 auth.json 文件配置 Basic Auth 凭据，需置于项目根目录或 ~/.composer/，权限设为 600；格式为 {“http-basic”: {“域名”: {“username”: “…”, “password”: “…”}}}，域名仅取 host 部分，不支持通配符；推荐用 composer config 命令安全写入。
在 auth.json 中配置 Basic Auth 凭据
Composer 会自动读取项目根目录或全局 COMPOSER_HOME 目录下的 auth.json 文件，用于向私有仓库或受保护的 Packagist 镜像提供 HTTP Basic Auth 认证信息。该文件必须是合法 JSON，且权限需设为 600（否则 Composer 会忽略）。
-
auth.json必须放在与composer.json同级（项目级）或~/.composer/（全局级），不能随意放置 - 内容格式严格：外层是
{"http-basic": {...}}，内层键名为仓库域名（不含协议和路径），值为含username和password的对象 - 密码中若含特殊字符（如
@、/、:），需 URL 编码，否则解析失败
{ "http-basic": { "packages.example.com": { "username": "deploy-user", "password": "s3cr3t%40Token" } } }通过 composer config 命令安全写入凭据
手动编辑 auth.json 容易出错，推荐用 Composer 自带命令生成。它会自动处理文件位置、权限和 JSON 格式，并支持交互式输入避免密码明文出现在 shell 历史中。
- 项目级配置（仅当前项目生效）：
composer config http-basic.packages.example.com deploy-user s3cr3t@token - 全局配置（所有项目共享）：
composer config --global http-basic.packages.example.com deploy-user s3cr3t@token - 命令执行后，Composer 自动创建
auth.json并设为600权限；若已存在，则只更新对应域名条目
当仓库地址含路径（如 https://repo.example.com/v1/）时怎么填域名？
Composer 只匹配 Host 部分，不关心路径和协议。无论你在 composer.json 的 repositories 中写的是 https://repo.example.com/v1/ 还是 http://repo.example.com/api，auth.json 中的键名都只需填 repo.example.com。
- 错误写法：
"https://repo.example.com/v1/": {...}或"repo.example.com/v1": {...} - 正确写法：
"repo.example.com": {...} - 如果多个子域需要不同凭据（如
pkgs.example.com和dev.pkgs.example.com），必须分别配置，不支持通配符
调试认证失败：为什么 Composer 仍报 401 Unauthorized？
常见原因不是凭据本身错误，而是匹配逻辑或环境问题。可启用详细输出定位：
- 加
-v参数运行命令（如composer update -v），观察日志中是否出现Reading /path/to/auth.json或Skipping auth.json: permissions are too open - 检查
auth.json文件权限：ls -l auth.json应显示-rw-------；若为644，执行chmod 600 auth.json - 确认
composer.json中仓库 URL 的 host 与auth.json键名完全一致（注意大小写、有无 www 前缀） - 某些反向代理或 cdn 会剥离
Authorization头，此时需联系运维确认是否透传该请求头
真正容易被忽略的是权限校验和域名匹配粒度——Composer 对 auth.json 的安全性要求极严，且不提示“为什么没加载”，只静默跳过；而域名必须精确到 Host，连端口号都要单独对待（如 repo.example.com:8080 和 repo.example.com 视为两个不同源）。