composer如何配置Satis构建内部离线源_composer企业级仓库管理【详解】

Satis 是静态包生成器，需配合 git 仓库、composer.json 和定期构建才能支撑企业级离线源；离线指不依赖 packagist.org，所有包须提前拉取并固化为 dist 归档。

直接上结论：Satis 不是“配置好就能用”的现成仓库，它本质是一个静态包生成器，必须配合 Git 仓库、composer.json 清单和定期构建流程才能支撑企业级离线源；离线 ≠ 完全断网，而是指不依赖 packagist.org，所有包需提前拉取并固化为 dist 归档。

如何初始化 Satis 配置文件（satis.json）

Satis 的行为完全由 satis.json 驱动，它不是 Composer 的 config.json，也不能用 composer config 生成。必须手写，且关键字段不能遗漏：

• name 和 homepage 是必需的，否则生成的 packages.json 缺失元信息，下游 composer install 会报 Could not parse version constraint
• repositories 列表里每个仓库必须是完整 Git URL（如 https://git.example.com/internal/lib-a.git），不支持本地路径或 svn
• require-all 设为 true 可自动抓取所有 tagged 版本；若只想要特定版本，改用 require 对象，例如：{"vendor/package": "1.2.*"}
• 务必显式设置 archive：它决定是否生成 .zip 或 .tar 离线包，没有它，Satis 只输出 packages.json，下游无法离线安装

构建时必须指定 dist 归档路径与格式

Satis 默认不下载任何代码，只生成元数据。要实现真正离线，必须让 Satis 把每个包的 dist 文件实际下载并存到本地目录。这靠 archive 配置驱动：

{   "name": "Internal Packagist",   "homepage": "https://satis.internal",   "repositories": [     {"type": "vcs", "url": "https://git.internal/lib-a.git"}   ],   "require-all": true,   "archive": {     "Directory": "dist",     "format": "zip",     "skip-dev": true   } }

注意：directory 是相对于构建命令执行路径的子目录，不是绝对路径；format 只能是 zip 或 tar，不能用 tgz；skip-dev 必须设为 true，否则会尝试归档 dev-master 这类不稳定分支，导致构建失败或体积暴增。

为什么 composer install 仍报 “package not found”？检查这三点

即使 Satis 构建成功，客户端 composer install 仍可能找不到包，常见原因有：

• 客户端 composer.json 中未正确声明私有源："repositories": [{"type": "composer", "url": "https://satis.internal/"}]，且 url 必须以 / 结尾，否则 packages.json 请求 404
• Satis 生成的 packages.json 里包名大小写与客户端 require 不一致（如 Satis 抓到 vendor/PackageA，但 composer.json 写了 vendor/packagea），Composer 区分大小写
• Git 仓库 tag 命名不规范：Satis 只识别符合 semver 的 tag（如 v1.0.0、1.2.3），release-1.0 或 master 不会被纳入 require-all 范围

离线环境部署的关键细节

所谓“离线”，是指客户端机器无法访问互联网，但 Satis 构建机必须能访问所有 Git 仓库和 github/gitlab（用于下载 dist）。最终交付物只有两个部分：

• 整个 Satis 输出目录（含 packages.json、dist/ 子目录、include/ 等），需整体拷贝到内网 Web 服务器（如 nginx）根目录
• 客户端机器的 composer.json 中 repositories URL 必须指向该内网地址，且确保该地址可被所有客户端 dns 解析（不能写 localhost 或私有 IP 未配置 hosts）
• 如果使用自签名 HTTPS 证书，客户端需提前在系统或 Composer 配置中信任该证书，否则 composer install 会因 ssl 验证失败中断

最易忽略的是：Satis 不处理包依赖的递归解析——它只按你给的仓库列表或 require 列表拉取，不会自动补全这些包所依赖的第三方包（比如你的内部包依赖 monolog/monolog）。那些也得显式加进 repositories 或 require，否则离线时就缺货。