直接用composer install会卡在packagist.org，是因为国内访问该源存在dns污染、tls握手超时及api响应慢等问题，composer默认需实时拉取全部元数据，即使只装单个包也必须连通官方源；satis通过本地化元数据和归档文件使安装完全绕过公网，但需确保satis.json配置精准、packages.json可web访问、项目中显式声明仓库并禁用packagist.org fallback。
为什么直接用 composer install 会卡在 packagist.org？
国内访问 packagist.org 不稳定，DNS 污染、TLS 握手超时、API 响应慢是常态。不是 Composer 本身慢，而是它默认所有包元数据都从官方源实时拉取——哪怕你只装一个 monolog/monolog，也要先连通 packagist.org 获取整个包的 dist 和 source 地址列表。Satis 的作用不是“加速下载”，而是把元数据和归档文件本地化，让 composer install 完全绕过公网。
搭建 Satis 镜像前必须确认的三件事
很多人跑完 php bin/satis build 却发现 Composer 还是走外网，问题往往出在前置条件没对齐：
-
satis.json里"repositories"列表必须只包含你真正需要镜像的包（支持name通配，如"yiisoft/yii2-*"），不能写成空数组或全量"*/*"—— Satis 不支持无限制抓取 - 生成的
packages.json必须放在 Web 可访问路径下（比如 Nginx 的/var/www/satis），且该目录需能被 Composer 直接 GET 到，路径结尾不能带/packages.json，否则 Composer 会拼成https://satis.example.com/packages.json/packages.json - 你的项目
composer.json中"repositories"必须显式声明为{"type": "composer", "url": "https://satis.example.com/"}，且"packagist.org"要设为false，否则 Composer 仍会 fallback 到公网
satis build 时常见失败原因和对应解法
执行 php bin/satis build satis.json web/ 报错，多数不是权限或 PHP 版本问题，而是配置与网络策略冲突：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 报错
Could not fetch https://api.github.com/repos/xxx/yyy：GitHub API 限流（未登录）或企业防火墙拦截。解决方法是在satis.json中加"github-protocols": ["https"]，并确保服务器能访问 GitHub 的 API 域名；若用 GitHub Token，需在环境变量设GITHUB_TOKEN，Satis 会自动读取 - 生成的
web/packages.json体积远小于预期：检查satis.json的"require-all"是否为true；如果设了"require-dependencies": true，但某些依赖包不在白名单里，Satis 就会跳过它们，不会报错也不会提示 - 镜像后
composer update提示Package xxx is not available：确认该包的name和version是否严格匹配satis.json中"require"的写法（例如"phpunit/phpunit": "^9.5"不等于"phpunit/phpunit": "9.5.*"）
如何让私有包和镜像共存而不冲突？
Satis 镜像本质是“只读缓存”，不处理私有代码托管（如 GitLab 私仓）。若项目同时依赖镜像包和公司内部包，composer.json 的 "repositories" 顺序就关键：
- 把私有仓库放前面，类型设为
"vcs"或"package"；Satis 镜像放后面，类型为"composer" - 避免在 Satis 配置中 include 私有包名——Satis 无法 clone 私有 Git 仓库（没凭据），强行写入会导致
build失败或静默跳过 - 如果私有包也想进镜像（比如统一分发、断网可用），得改用
"package"类型手动定义，并把 dist 归档提前放到 Satis 的web/目录下，再通过"dist": {"url": "...", "shasum": "..."}指向它
镜像不是万能代理，它只做两件事：按需抓取、静态发布。复杂权限控制、动态版本解析、私有协议支持，都不在它的职责范围内。
