根本原因是composer默认只查packagist.org，必须显式注册type为"composer"、url以/结尾且配置正确认证的私有仓库，否则会静默跳过；satis生成的packages.json路径错误、认证文件位置不对或archive未启用也会导致拉取失败。
私有镜像不是配个 URL 就能用的，核心卡点在 satis 生成的静态文件能否被 Composer 正确识别、拉取和解析。绝大多数失败都发生在构建阶段或客户端配置环节，而不是部署本身。
为什么 composer install 找不到私有包？
根本原因不是包没上传，而是 Composer 根本没去你的私有源查——它默认只查 packagist.org。必须显式注册仓库，且类型、URL 格式、认证三者全对，才可能触发查找。
-
"type": "composer"是硬性要求，写成"vcs"或漏掉会静默跳过 -
url必须以/结尾，否则 Composer 拼出的packages.json路径是错的（比如https://pkgs.example.com/packages.json→ 实际要的是https://pkgs.example.com//packages.json） - 如果私有包托管在 GitHub/GitLab，
satis.json里repositories的url必须可被satis build克隆（SSH key 或 HTTPS token 需提前配置好，否则包会被静默跳过，不报错）
satis.json 里 require 和 require-all 怎么选？
用 require-all: true 看似省事，但会导致 packages.json 文件体积爆炸，Composer 加载时内存溢出或超时。企业级场景必须收敛范围。
- 只同步明确需要的包：
"require": { "acme/logging-bundle": "^2.1", "acme/auth-sdk": "dev-main" } - 避免使用通配符：
"acme/*": "*"不被支持，会直接忽略 - 如果依赖 dev 分支，确保 Git 仓库允许
dev-前缀分支被索引（部分私有 Git 服务默认关闭）
认证凭据放哪？auth.json 的三个生效位置
Composer 查找认证文件是有固定顺序的，放错地方就等于没配。
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 当前项目目录下的
auth.json（最高优先级，适合 CI 临时注入） -
$COMPOSER_HOME/auth.json（推荐用于团队统一配置，$COMPOSER_HOME通常是~/.composer） -
$HOME/.composer/auth.json（旧版路径，兼容用，不建议新项目使用）
CI 环境最容易踩坑：Docker 容器里没挂载 $COMPOSER_HOME，结果它读了空的全局 auth.json，报 Authentication required 却死活登不上。
启用 ZIP 包分发必须配 archive
不配 archive，composer install --prefer-dist 会退回到 --prefer-source，也就是直接 clone Git 仓库——这不仅慢，还可能因权限问题失败。
- 必须显式开启：
"archive": { "directory": "dist", "format": "zip", "skip-dev": true } -
output-dir和archive.directory是两个路径：前者是packages.json输出位置，后者是 ZIP 包存放位置，需确保 Web 服务器能同时访问两者 - Web 服务器（Nginx/Apache）必须正确设置 MIME 类型，否则浏览器会把
.zip当作文本下载，Composer 也拉不到
真正难的不是搭起一个能返回 packages.json 的页面，而是让这个 JSON 里每一条包记录都指向可访问、可认证、可下载的真实 ZIP 或 Git 地址——中间任何一环断开，composer install 就只会安静地失败。
