Composer私有包401错误源于HTTP Basic认证缺失，需通过composer config命令在auth.json中配置http-basic凭据，优先使用项目级或全局配置，避免明文密码泄露和Git提交。
Composer安装私有包时提示401 Unauthorized
这是最典型的HTTP Basic认证缺失表现。Composer默认不携带凭据访问需要认证的仓库（比如私有Packagist、GitLab私有仓库、Nexus PHP repo），直接返回401 Unauthorized或Could not fetch https://...: Failed to decode response: Syntax error（因返回HTML登录页而非JSON）。
解决路径只有一条：让composer install或composer update能自动带上Authorization: Basic xxx头。不靠改源码，也不靠临时加-H参数——那不可持久。
- 优先使用
composer config命令写入全局或项目级凭据，它会自动base64编码并存进auth.json - 手动编辑
auth.json也行，但必须确保http-basic字段结构正确，且密码不含未转义的特殊字符（如@、/） - 凭证作用域按域名精确匹配：
https://repo.example.com和https://api.repo.example.com需分别配置
用composer config命令添加Basic认证凭据
这是最安全、最推荐的方式，避免手误和明文密码泄露风险。命令会校验格式，并把加密后的凭据写入对应层级的auth.json（项目根目录或COMPOSER_HOME）。
向私有仓库https://packages.example.org添加用户deploy和密码abc123：
composer config http-basic.packages.example.org deploy abc123
该命令等价于在auth.json中写入：
{
"http-basic": {
"packages.example.org": {
"username": "deploy",
"password": "abc123"
}
}
}
- 若想写入全局配置（所有项目生效），加
--global参数：composer config --global http-basic.packages.example.org deploy abc123 - 密码含
$、!等shell元字符时，务必用单引号包裹：composer config http-basic.example.com user 'p@ss$w!rd' - 执行后可运行
composer config --list --global | grep http-basic确认是否写入成功
auth.json文件位置与加载优先级
Composer按固定顺序查找auth.json，找到即停。高优先级配置会覆盖低优先级同域名设置。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 项目根目录下的
auth.json（最高优先级） -
COMPOSER_HOME目录下的auth.json（默认是~/.composer/auth.json或%APPDATA%\Composer\auth.json） - 不存在则无认证凭据，所有
http-basic请求失败
注意：auth.json不应提交到Git。把它加进.gitignore，尤其当配置的是全局凭据时——否则等于把密码公开。
如果项目CI环境需要凭据，别硬编码进auth.json，改用环境变量注入：COMPOSER_AUTH='{"http-basic": {"packages.example.org": {"username": "xxx", "password": "yyy"}}}' composer install。
Git仓库URL含Basic认证时的陷阱
有人会把用户名密码直接写进composer.json的repositories里，比如："url": "https://user:pass@gitlab.example.com/group/repo.git"。这看似可行，但问题很多：
- Git客户端可能忽略URL中的凭据（尤其是较新版本Git），导致克隆失败
- 密码明文暴露在
composer.json中，极易泄露 - Composer 2.2+ 已明确警告这种写法：
Deprecated: Credentials in repository URLs are deprecated
正确做法是：把Git仓库地址写成干净URL（不含凭据），再通过auth.json统一管理认证。例如：
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/group/repo.git"
}
]
然后用composer config http-basic.gitlab.example.com user pass补上凭据。这样既解耦，又符合Composer演进方向。
实际调试时，加-vvv参数看Composer底层请求头：composer install -vvv 2>&1 | grep Authorization，能直接验证凭据是否被发出。
