本地镜像源需部署http服务（如satis），非composer内置功能；本地缓存则通过统一composer_cache_dir路径复用zip包，二者技术路径不同，不可混淆。
本地镜像源 ≠ 本地缓存，别混淆概念
Composer 本身不提供“本地镜像源”功能，所谓“本地搭建镜像源”，实际是部署一个能响应 packages.json 和 dist/ ZIP 请求的 HTTP 服务（如 Satis、Private Packagist 或 packagist-mirror）。直接改 composer config -g repo.packagist 只能切到阿里云、清华等公开镜像，无法实现局域网内离线或加速私有包分发。
如果你真正想解决的是“避免重复下载 ZIP 包”“提升多项目构建速度”“支持离线安装”，那你要的其实是 本地缓存复用，不是镜像源。两者常被混谈，但技术路径完全不同：
- 镜像源：需 Web 服务 + 域名 + HTTPS（或信任自签证书）+ 正确 MIME 类型 +
packages.json索引文件可 GET - 本地缓存：只需统一
COMPOSER_CACHE_DIR路径 + 权限可控 + 跨构建复用~/.composer/cache/files/下的 ZIP 压缩包
为什么 Satis 搭建后仍 404？检查这四点
Satis 是最轻量的私有源生成工具，但它不运行服务，只输出静态文件。404 不是配置错，而是 Web 层没对齐：
-
root必须精确指向 Satis 的output-dir，例如 Nginx 配置中root /var/www/satis/web;，不能少一级 - 必须显式声明 JSON 支持：
types { application/json json; }，否则返回text/plain，Composer 直接拒收 - 访问
https://pkgs.internal/packages.json要成功；但更要验证dist/下 ZIP 是否可直连，如https://pkgs.internal/dist/monolog/monolog/2.10.0/7a8e0d4b12c3.zip—— SELinux、文件权限、URL 末尾斜杠缺失都可能导致 404 - 根路径
https://pkgs.internal/默认找index.html，而 Satis 不生成它；要么加index packages.json;，要么确保用户访问时明确带路径
项目级 repositories 怎么写才不被忽略
只要项目根目录 composer.json 中存在 repositories 字段，全局 repo.packagist 配置就完全失效。正确写法必须满足三个硬性条件：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 私有源必须放在
repositories数组第一位，Composer 按顺序查找，同名包不会合并 -
"packagist.org": false必须作为独立项写在repositories数组里，不是嵌套在某个仓库对象内部 - 每个仓库对象的
type必须是"composer"，url必须以https://开头且以/结尾（如"https://pkgs.internal/"） - 不要用
require-all: true，它会触发全量同步，耗时且无必要；按需同步指定包更稳
示例片段：
{
"repositories": [
{
"packagist.org": false
},
{
"type": "composer",
"url": "https://pkgs.internal/"
}
]
}
COMPOSER_CACHE_DIR 挂载失败的典型表现
缓存路径不对，镜像再快也白搭。常见失败现象包括：
- Jenkins 构建卡在
Downloading monolog/monolog，日志却显示请求的是https://packagist.org/...—— 实际是缓存未命中，被迫回退网络 - Docker agent 中
composer install每次都重下 ZIP，ls -l ~/.composer/cache/files/发现目录为空或属主为root - 离线环境报
Could not fetch，但find $(composer config --global cache-dir)/files -name "*7a8e0d4b*.zip"找不到对应文件 —— 缓存路径含中文、版本不一致或未提前迁移完整
关键动作只有两个：export COMPOSER_CACHE_DIR=/shared/composer-cache（所有构建环境一致），以及确保该路径由 Jenkins 用户（或容器内运行用户）可读写。别依赖默认 $HOME，尤其 Windows 下 $env:USERPROFILE 可能含中文。
