如何用 Satis 精确镜像单个包的指定版本（而非整库）-php教程-PHP中文网

如何用 Satis 精确镜像单个包的指定版本（而非整库）

本文详解如何通过 Satis 的 "type": "package" 配置方式，将本地 ZIP 包（如手动下载的 GitHub Release）注册为可被 Composer 安装的私有依赖，避免拉取整仓所有分支/Tag，实现轻量、可控、离线友好的私有包管理。

本文详解如何通过 satis 的 `"type": "package"` 配置方式，将本地 zip 包（如手动下载的 github release）注册为可被 composer 安装的私有依赖，避免拉取整仓所有分支/tag，实现轻量、可控、离线友好的私有包管理。

在使用 Satis 构建私有 Composer 仓库时，一个常见误区是认为必须通过 "type": "vcs"（如 git）引入整个代码仓库——这会导致 Satis 默认抓取所有 Tag 和分支，生成冗余元数据，既耗时又占用磁盘空间，尤其当目标仅是某个稳定版 ZIP 发布包时（例如 doctrine/inflector 2.0.4 的官方 Release ZIP）。

正确的做法是改用 "type": "package" 模式，它允许你完全绕过 VCS 扫描，直接声明一个“静态包”：只需提供包名、精确版本号及 dist 文件的本地或远程 URL。这种方式语义清晰、构建极快，且天然支持离线部署。

✅ 正确配置示例（混合 VCS + 单 ZIP）

以下 satis.json 展示了如何同时管理一个 Git 仓库（Laravel 主干）和一个本地 ZIP 包（Doctrine Inflector 特定版本）：

{
  "name": "Internal Package Mirror",
  "homepage": "https://packages.internal",
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "doctrine/inflector",
        "version": "2.0.4",
        "type": "library",
        "autoload": {
          "psr-4": { "Doctrine\Inflector\": "lib/" }
        },
        "dist": {
          "url": "https://packages.internal/dist/doctrine-inflector-2.0.4.zip",
          "type": "zip"
        }
      }
    },
    {
      "type": "vcs",
      "url": "https://github.com/laravel/laravel.git"
    }
  ],
  "require-all": false,
  "require": {
    "doctrine/inflector": "^2.0.4",
    "laravel/laravel": "dev-main"
  },
  "archive": {
    "directory": "dist",
    "format": "zip",
    "prefix-url": "https://packages.internal",
    "skip-dev": true
  },
  "config": {
    "secure-http": true,
    "preferred-install": "dist"
  }
}

? 关键要点说明：

"type": "package" 块内嵌 "package" 对象，不再需要 url 字段（与 vcs 类型完全不同）；

version 必须为合法语义化版本字符串（如 "2.0.4"），不可写 "dev-main" 或 "stable"；

dist.url 应指向 Web 可访问路径（如 Nginx 的 dist/ 目录），Satis 不会自动下载或解压该 ZIP——你需提前将 ZIP 放入对应位置，并确保其结构符合 Composer 加载规范（如含 composer.json 和正确目录层级）；

"require-all": false 是必须项，否则 Satis 仍会尝试扫描 vcs 仓库全部版本；应改用显式 "require" 列出所需包及其约束；

若 ZIP 来自本地文件系统（开发调试阶段），可临时用 file:// 协议（如 "url": "file:///var/www/satis/dist/inflector.zip"），但生产环境务必使用 HTTP(S) 地址，以保证客户端 Composer 能正常 GET。

⚠️ 注意事项与排错提示

ZIP 内容必须合规：包 ZIP 解压后应包含有效的 composer.json（含 name、version、autoload 等），且源码路径需与 autoload 声明一致。建议用 unzip -l xxx.zip 核查结构。
不要混用 require-all 与 package：二者逻辑冲突。require-all: true 会强制忽略 require 字段并全量抓取 VCS，导致你的 package 配置失效。

客户端 composer.json 需精准匹配：项目中声明依赖时，版本约束必须能命中 Satis 中定义的精确版本，例如：

"require": {
  "doctrine/inflector": "2.0.4"   // ✅ 严格匹配
  // "doctrine/inflector": "^2.0"  // ⚠️ 若未镜像 2.0.x 其他版本，将失败
}

HTTPS 安全限制：若 dist.url 使用 HTTP，需在 Satis 配置中设 "secure-http": false（不推荐生产环境）；更佳实践是配置反向代理或 Let’s Encrypt 证书，启用 HTTPS。

✅ 总结

Satis 的 "type": "package" 是实现「按需镜像」的核心能力——它把包管理从“仓库同步”降维为“资源注册”，特别适合：

引入第三方闭源 ZIP 发行版；
回滚至历史稳定版（无需维护旧 Git 仓库）；
在 CI/CD 流水线中动态注入构建产物（如 dist/mylib-1.2.3.zip）；
搭建零网络依赖的离线安装源。

只要配置严谨、路径可达、版本明确，你就能用几行 JSON，让 Composer 如丝般顺滑地安装任意 ZIP 包，彻底告别 composer install 卡死在 packagist.org 的时代。