“动态按需缓存”不能靠改repo.packagist实现，因为该配置仅替换元数据入口（packages.json），不接管ZIP下载路径；当dist.url指向GitHub/GitLab等外网地址时，Composer仍直连这些不可达或需鉴权的地址，导致下载卡在403或超时，根本原因在于Composer v2协议中元数据与分发资源解耦。
为什么“动态按需缓存”不能靠改 repo.packagist 实现
改 composer config -g repo.packagist 只换元数据入口，不接管 ZIP 下载路径。私有云里一旦包的 dist.url 指向 GitHub/GitLab/自建 Git 仓库，Composer 仍会直连这些地址——而它们在内网不可达或需鉴权。结果就是：composer install 能读到包列表，但卡在 “Downloading xxx.zip” 这一步，报 403 Forbidden 或超时。
根本问题在于 Composer 的 v2 协议设计：元数据（packages.json）和分发资源（ZIP）是解耦的。镜像服务若只同步前者，没做反向代理层兜底，就不是真正可用的“按需缓存”。
- 用
composer show vendor/package --verbose查看实际dist.url，确认是否落在私有云可控域内 - 若
dist.url是https://github.com/...类地址，必须部署反向代理（如 Nginx +proxy_pass），并在响应头透传X-OAuth-Scopes或注入 token - 不支持
dist.type: "package"的私有包，得提前用 Satis 打包进 artifact 目录，再配"type": "artifact"仓库
用 Nginx 做反向代理实现真·按需缓存
这是目前私有云中最可控、最低维护成本的方案：Nginx 不生成静态文件，只在首次请求时拉取远程 ZIP 并缓存，后续直接 serve。关键不是“预同步”，而是“第一次访问才拉，拉完就缓”。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 必须开启
proxy_cache_valid 200 302 1h;，否则默认不缓存重定向（GitHub Releases 返回 302） -
proxy_set_header Authorization "token xxx";要加在 location 块里，且 token 必须有read:packages权限（GitHub）或对应 scope（GitLab） - 缓存 key 必须包含
$scheme$host$request_uri，避免 HTTPS 和 HTTP 请求混用同一缓存项 - 别漏掉
proxy_ignore_client_abort on;，否则用户 Ctrl+C 中断下载会导致缓存损坏
repositories 配置必须禁用 packagist.org 且显式声明类型
私有云中只要留着默认源，Composer 就可能 fallback 回外网——尤其当内部镜像返回 404 或超时，它不会报错，只会默默慢等 30 秒后切走。这不是容错，是故障放大器。
- 项目
composer.json里必须写："packagist.org": false，位置在repositories数组末尾 - 内部镜像仓库
type字段只能是"composer"，写成"package"或空值会导致语义版本解析失败（^2.0匹配不到） - URL 必须以
/结尾，否则packages.json请求会 404（Nginx 默认不自动补斜杠） - 验证是否生效：运行
composer install -vvv，看日志里所有GET请求是否都命中你配置的域名，而非repo.packagist.org
缓存失效和冷启动的两个隐藏雷区
按需缓存最怕“看似正常，实则每次重下”。常见于 lock 文件微小变动或缓存目录权限错位。
-
composer.lock里任何字段变更（包括注释、空格、换行符）都会让 Composer 认为依赖图已变，跳过 dist 缓存，强制重 fetch —— CI 构建前务必跑composer update --lock格式化 - 私有云节点若用 NFS 挂载缓存目录，
file_put_contents()可能静默失败，日志只显示Failed to write cache file，需检查挂载参数是否含noac或actimeo=0 - 不要复用开发机的
~/.cache/composer目录，不同 PHP 版本生成的缓存结构不兼容，会导致哈希校验失败后反复重下
