必须启用"archive": {"format": "zip"}和"require-dependencies": true，否则Satis仅生成元数据不下载ZIP包且缺失子依赖，导致composer install报Could not find package。
用 Satis 构建镜像前必须启用 archive 和 require-dependencies
很多人跑完 satis build 发现离线机上 composer install 仍报 Could not find package，根本原因是 Satis 默认只生成 packages.json，不下载 ZIP 包，也不递归抓取子依赖（比如 monolog/monolog 依赖的 psr/log）。光有元数据，没 ZIP，Composer 在安装阶段就会卡住。
确保 satis.json 包含以下关键配置：
-
"archive": {"format": "zip", "skip-dev": true}—— 否则dist/目录为空，composer install找不到 ZIP -
"require-dependencies": true—— 必须开启，否则间接依赖元数据缺失，解析失败 -
"require-all": false，改用显式"require"列出顶层包（如"laravel/framework": "10.48.12"）——避免同步全量 Packagist（可能超 40GB） - 不要混用
require和require-all: true，Satis 会静默忽略require
构建后必须验证 ZIP 文件名是否合规
Composer 只认严格命名的 ZIP：格式为 vendor-name-version.zip（例如 monolog-monolog-2.9.1.zip），多一个斜杠、下划线或大小写错误都会被跳过。手动生成或重命名极易出错。
检查方式：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 进入
web/dist/目录，运行ls -1 | head -n 3，确认文件名不含/、_或多余空格 - 打开
web/packages.json，找任意包的dist.url字段，值应为相对路径，如"dist/monolog-monolog-2.9.1.zip"，不能是"https://..."或"../dist/..." - 用
composer archive --format=zip --dir=./test对单个包验证 ZIP 内容与composer.lock中的dist.shasum是否一致
离线机必须用 HTTP 服务托管，file:// 协议不可靠
Composer 2+ 明确禁用 file:// 协议作为仓库源，哪怕路径正确也会报 Invalid repository type: file:。Docker、CI 环境或不同用户权限下，file:// 更易因空格、编码或权限崩溃。
最小可行方案：
- 把 Satis 输出的
web/目录拷到离线机，执行：python3 -m http.server 8000 --directory ./web - 访问
http://127.0.0.1:8000/packages.json能返回 JSON，且响应头含Content-Type: application/json（Nginx/Apache 需手动配 MIME 类型） - URL 必须用
http://127.0.0.1:8000或局域网 IP（如http://192.168.10.100:8000），避免用localhost（部分 PHP 环境 DNS 解析异常） -
satis.json中的archive.prefix-url必须与实际服务地址一致，否则 ZIP 下载链接 404
项目级配置要双保险：禁用 packagist.org + 显式声明本地源
只改 composer.json 的 repositories 不够。Composer 默认 fallback 到官方源，插件（如 symfony/flex）可能绕过项目配置偷偷联网。
必须同时做两件事：
- 项目
composer.json顶部加："repositories": [{"type": "composer", "url": "http://127.0.0.1:8000"}], "packagist.org": false - 全局禁用：
composer config -g repo.packagist false（不是--unset，而是设为false） - 清缓存：
composer clear-cache，否则可能读旧packages.json - 验证：
composer install -v输出中必须出现Reading packages.json from http://127.0.0.1:8000/packages.json，不能有任何Downloading https://repo.packagist.org/
archive.prefix-url 的一致性。两者任一出错，Composer 都不会报明确错误，而是静默跳过包，最终在 Resolving dependencies 阶段卡死或报 Package not found。 
