私有 Packagist 必须用 Satis 生成静态 packages.json 和 dist 包，而非实时同步；需正确配置 satis.json 的 archive、homepage 和 web 服务，确保 packages.json 可 HTTP 访问且 Content-Type 正确，下游项目 repositories.url 指向该地址并以 / 结尾。
私有 Packagist 平台必须用 Satis 构建，不是“配置同步路径”而是生成静态索引
Composer 没有内置的“同步路径”概念，所谓“自建私有 Packagist”实际是用 Satis 生成一个静态 packages.json 文件及其配套 dist 包，供其他项目通过 "type": "composer" 源拉取。这不是实时代理，也不走 webhook 同步——每次更新都要手动或 CI 触发 php bin/satis build。
关键点：
-
satis.json中的"archive"配置决定 dist 包存放位置，例如"web/dist"，但该路径是相对于satis build命令执行目录的输出路径，不是远程可写“同步地址” - 生成的
packages.json必须能被 HTTP 直接访问（如https://packages.internal/packages.json），且返回200和合法 JSON；Satis 不提供服务端逻辑，需搭配 Nginx/Apache 或 CDN 托管静态文件 - 不要在
satis.json里写"url": "https://packages.internal"这类“同步目标”，那是给下游项目用的repositories.url，不是 Satis 自身的上传地址
satis.json 的 archive 配置直接影响 dist 包生成位置和 URL 可达性
"archive" 块控制 ZIP 包是否生成、格式、是否跳过 dev 分支，但它不决定“推送到哪”，只决定“生成到哪”。下游项目最终下载的 dist.url 是由 "homepage" + "archive.format" + 包名版本拼出来的。
常见错误配置：
- 漏掉
"homepage"：导致生成的packages.json里dist.url是相对路径（如"dist/acme-utils/acme-utils-zip-1.2.3.zip"），下游项目无法解析 -
"homepage"写成内网地址（如"http://192.168.1.100"）：CI 或外部开发者访问不到 -
"archive.format"设为"tar"但 Web 服务器没配Content-Type: application/x-tar：浏览器或 Composer 下载失败且无明确报错 -
"skip-dev": false：把dev-main分支也打包进 dist，但 ZIP 包名含dev-main这种非法字符，导致下游composer install解压失败
下游项目 composer.json 的 repositories.url 必须指向 packages.json 的 HTTP 地址
项目不能直接 require 私有 Git 仓库，也不能把 Satis 输出目录当 URL。正确做法是让 repositories.url 指向托管 packages.json 的 HTTP 路径，且末尾带 /。
例如 Satis 输出到 /var/www/packages.internal/，其中 packages.json 在根目录，则项目中写：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
"repositories": [
{
"type": "composer",
"url": "https://packages.internal/"
}
]
注意：
- URL 必须以
/结尾，否则 Composer 请求https://packages.internal/packages.json会 404（Nginx/Apache 默认不自动补斜杠） - 不能写成
"https://packages.internal/web/"或"https://packages.internal/packages.json"，前者路径错，后者是文件地址，不是源地址 - 如果用了 CDN，确保
packages.json和所有dist/*.zip都被缓存且支持 CORS（尤其跨域 CI 场景）
验证 Satis 是否真正生效：看 composer show 输出的 dist.url
光看 composer update 成功不够，必须确认它真从私有源拉包，而不是 fallback 到 packagist.org。
运行：
composer show acme/utils --verbose
检查输出中是否包含类似：
dist : {"type":"zip","url":"https://packages.internal/dist/acme-utils/acme-utils-zip-1.2.3.zip","reference":"abc123"}
如果 url 指向 packagist.org 或 github.com，说明：
-
repositories数组里没放 Satis 源，或顺序不对 - 没显式禁用 packagist.org（即缺
{"packagist.org": false}同级配置） - 项目
composer.json的require版本约束写成了"dev-main"，但 Satis 没开启"archive.skip-dev": true，导致该版本未被收录
最隐蔽的坑是：Satis 生成了 packages.json，但 Web 服务返回的是 text/plain MIME 类型，Chrome 可能显示 JSON，而 Composer 内部解析失败且静默 fallback —— 此时务必检查 curl -I https://packages.internal/packages.json 的 Content-Type 响应头。
