composer如何自建私有仓库_使用satis搭建composer镜像【进阶】

Satis 是静态包索引生成器而非镜像，它不代理或缓存请求，仅根据配置拉取 git 仓库的 composer.json 并生成静态 packages.json 和 ZIP 归档，适用于内网管控与离线环境，不支持实时同步。

为什么 satis 不是“镜像”，而是“静态包索引生成器”

很多人搜“composer 私有仓库 镜像”，结果用 satis，却发现它根本不能实时同步 packagist.org 或其他源——satis 从不代理请求，也不缓存 http 流量。它只做一件事：读取你给的 packages.json 列表（或 github 组织），拉取对应 Git 仓库的 composer.json，解析后生成静态 packages.json 和一堆 .zip 归档文件，全部扔进一个 Web 可访问目录里。

所以它适合内网统一管控、发布前审核、或离线环境；不适合替代 packagist.org 的实时镜像（那得用 toran proxy 或 private-packagist）。

• 你改了某个私有包的 composer.json？satis build 不会自动感知，必须手动重跑
• 想支持 dev-main 这类分支别名？得在 satis.json 里显式配置 "require-dependencies": true 和 "require-dev-dependencies": false 等开关
• satis build 默认只抓 dist（zip/tar），不生成 source（git clone 地址），除非你加 "archive": {"format": "zip", "skip-dev": false}

satis.json 最容易写错的三个字段

新手常卡在构建失败，报错类似 Could not find package xxx at any version，其实多半是 satis.json 结构没对齐。重点盯这三个：

• "name"：只是显示名，不影响功能，但若为空，某些旧版 satis 会警告
• "repositories"：必须是数组，每个元素是完整仓库定义，不是只写 URL；比如 GitHub 私仓要写成 {"type": "vcs", "url": "https://github.com/your-org/private-lib"}，不能只填字符串
• "require-all" 或 "require"：前者表示拉取所有已知仓库的全部稳定版本，后者是精确指定 {"vendor/package": "*"}；混用会冲突，建议二选一

示例片段：

{   "name": "My Private Repo",   "homepage": "https://packages.internal",   "repositories": [     {"type": "vcs", "url": "https://gitlab.internal/lib-a"},     {"type": "vcs", "url": "https://gitlab.internal/lib-b"}   ],   "require-all": true,   "archive": {"format": "zip", "skip-dev": true} }

构建后 composer install 报 file could not be downloaded

这通常不是网络问题，而是路径或权限没配对。Satis 生成的 dist 文件默认放在 dist/vendor-package/version-hash.zip，而你的 Web 服务器（nginx/apache）必须让这个路径可被直接 GET 到。常见断点：

• Web 根目录没指向 satis build 输出目录（比如你 satis build satis.json web/，但 Nginx root 指向的是 /var/www/html）
• URL 路径含多余前缀，比如 Satis 生成的是 https://pkgs.example.com/dist/...，但你在 composer.json 的 repositories 里写成了 "url": "https://pkgs.example.com"（缺了 /packages.json 后缀，实际应为 "url": "https://pkgs.example.com/packages.json"）
• Git 仓库本身没打 tag，satis 就不会为 1.0.0 这类版本生成 dist 包，只会留 dev-main —— 此时 composer install 会 fallback 到 source（git clone），若内网禁止出向 Git，则直接失败

PHP 版本和扩展限制经常被忽略

satis 是 PHP 脚本，构建过程依赖很多底层能力。不是装了 PHP 就能跑：

• 最低要求 PHP 7.4（satis 1.0+），但如果你的私有包用了 PHP 8.1 语法，而构建机只有 PHP 7.4，satis 解析其 composer.json 会失败（哪怕只是读取，不执行）
• 必须启用 openssl 扩展（HTTPS Git 克隆）、zlib（解压 zip）、json（解析元数据）；禁用 allow_url_fopen 会导致无法 fetch 远程仓库的 composer.json
• Git 二进制必须在 $PATH 中，且版本 ≥ 2.10（老 Git 对 shallow clone 支持差，拉大仓库极慢甚至卡死）

构建前快速检查：

php -m | grep -E '^(openssl|zlib|json)$' which git php -v

复杂点在于：有些公司用容器化构建，但基础镜像里 Git 或 OpenSSL 版本太旧，错误表现却是“超时”或“空响应”，而不是明确报错。