私有仓库离线部署需提前镜像全部依赖，包括递归依赖、dev分支及dist/source包；satis仅生成静态索引，必须联网时全量构建，禁用packagist并精确配置satis.json require列表，确保php环境与离线机完全一致。
私有仓库必须提前镜像所有依赖
离线环境部署 composer 的核心不是“装上就能用”，而是把项目依赖链上所有包（包括递归依赖、dev 分支、dist 和 source 两种分发方式）完整拉下来，存成可离线访问的静态索引。Satis 本身不代理请求，它只生成一个静态 packages.json 和一堆压缩包快照——所以镜像动作必须在有网时完成，且要覆盖全。
常见错误是只跑一次 satis build，结果发现某个 require-dev 包没进仓库，或者用了 "minimum-stability": "dev" 却漏了 dev-master 分支的 commit。
- 运行
satis build前，确保repositories配置里包含所有上游源（如 packagist.org、GitHub、GitLab 私有实例），否则 Satis 不知道去哪抓 - 显式指定
--skip-errors很危险：它会让构建跳过失败包，但你根本不会意识到缺了啥；建议先不加，逐个修通再批量跑 -
archive: { format: "zip", skip-dev: false }必须设为false，否则开发用的require-dev包不会被打包
composer.json 里不能写 packagist.org
离线环境最常踩的坑：项目 composer.json 还保留着默认的 packagist.org 配置，导致 composer install 一启动就报 Could not fetch https://repo.packagist.org/packages.json，哪怕本地仓库地址已配好。
必须彻底禁用默认源，只留私有仓库。这不是“加一个”而是“换一个”。
- 执行
composer config --global repo.packagist false，全局关掉 packagist - 在项目根目录下运行
composer config repository.my-satis composer https://your-satis-server.com，地址必须能被离线机器解析和访问（建议用内网 DNS 或 hosts 绑定） - 检查生效：运行
composer config -l | grep repo，确认输出里只有你的私有仓库，没有packagist.org相关行
satis.json 的 require 必须穷举所有用到的包
Satis 不会自动分析你的项目 composer.json，它只按你写的 satis.json 中 require 字段去拉取。漏写一个包，离线安装时就会卡在 Installing vendor/package (1.2.3) 然后报 Package not found。
尤其注意那些间接依赖：比如你只写了 "monolog/monolog"，但实际项目用了 symfony/console，而它又依赖 psr/log——如果 psr/log 没列在 satis.json 里，Satis 就不会镜像它。
- 用
composer show --tree在联网机器上展开完整依赖树，复制所有顶层 + 二级包名到satis.json的require - 别信
"*"：Satis 不支持通配符，"*"会被忽略 - 版本写法尽量宽泛但可控，例如
"^7.4 || ^8.0"比死锁"7.4.5"更稳妥，避免频繁重镜像
离线机器上的 PHP 环境必须匹配构建环境
Satis 生成的 zip 包本身不带 PHP 版本逻辑，但 Composer 安装时会校验 php 平台约束（如 "php": "^8.1"）。如果离线机器是 PHP 7.4，而镜像时用了 PHP 8.2 构建，某些包的 composer.json 里写了 "php": "^8.2"，安装就会直接拒绝，报错 Your requirements could not be resolved。
更隐蔽的问题是扩展依赖：比如某包声明 "ext-gd": "*"，但离线机器没装 gd 扩展，Composer 不会提前报错，直到运行时才崩。
- 镜像前，在联网机器上用和离线环境**完全一致**的 PHP 版本、扩展、
php.ini设置跑satis build - 离线机器执行
composer install前，先跑composer check-platform-reqs，它会列出所有缺失的 PHP 版本或扩展 - 不要依赖
composer install --ignore-platform-reqs：这能绕过检查，但运行时报错更难排查
