如何用 Satis 精确引入单个 ZIP 包（而非整库克隆）-php教程-PHP中文网

如何用 Satis 精确引入单个 ZIP 包（而非整库克隆）

本文详解如何在 Satis 中通过 "type": "package" 方式声明本地或远程 ZIP 归档包，跳过 Git 克隆与全量版本扫描，实现对特定版本的精准收录与分发。

本文详解如何在 satis 中通过 `"type": "package"` 方式声明本地或远程 zip 归档包，跳过 git 克隆与全量版本扫描，实现对特定版本的精准收录与分发。

Satis 默认通过 "type": "vcs"（如 git）拉取整个仓库并解析所有分支/Tag，导致生成大量冗余包元数据与归档文件。但当您只需发布一个已构建好的 ZIP 包（例如从 GitHub Release 下载的 v2.0.4.zip，或 CI 打包生成的内部组件压缩包），应改用 "type": "package" 模式——它不依赖 Git，而是直接描述单个包的完整信息，由 Satis 静态注入到 packages.json 中。

✅ 正确语法：使用 `package` 类型声明 ZIP 包

以下为最小可行配置片段，关键点已加注释：

{
  "name": "Internal Package Hub",
  "homepage": "https://packages.internal",
  "repositories": [
    {
      "type": "package",
      "package": {
        "name": "doctrine/inflector",
        "version": "2.0.4",
        "type": "library",
        "dist": {
          "url": "https://packages.internal/dist/inflector-2.0.4.zip",
          "type": "zip"
        },
        "autoload": {
          "psr-4": {
            "Doctrine\Inflector\": "lib/"
          }
        }
      }
    },
    {
      "type": "vcs",
      "url": "https://github.com/laravel/laravel.git"
    }
  ],
  "require": {
    "doctrine/inflector": "2.0.4",
    "laravel/laravel": "dev-main"
  },
  "archive": {
    "directory": "dist",
    "format": "zip",
    "prefix-url": "https://packages.internal"
  }
}

⚠️ 注意事项：

"type": "package" 必须包裹在 "package" 子对象内（不可直接写在 repositories 数组元素顶层）；

"version" 字段必须显式指定，且需符合 Semantic Versioning 规范（如 2.0.4、1.2.x-dev），不能是 dev-master 或 latest；

"dist.url" 应指向 Web 可访问路径（非本地文件系统路径），Satis 不会自动上传 ZIP 文件，需手动将 inflector-2.0.4.zip 放入 dist/ 目录，并确保 Web 服务器能公开提供该 URL；

若 ZIP 内部结构与标准 Composer 包不一致（如无 autoload 配置），请务必补全 "autoload" 字段，否则下游项目无法自动加载类；

"require" 字段需显式列出该包及其版本，与 repositories 中定义呼应；"require-all": true 与 "require" 互斥，不可共存——此处必须删掉 require-all，仅保留 require。

? 构建与部署流程（关键三步）

准备 ZIP 文件
将目标 ZIP 重命名为规范格式（如 vendor-name-package-name-version.zip），上传至 Satis 输出目录的 dist/ 子目录下（例如 /var/www/satis/dist/doctrine-inflector-2.0.4.zip）。
运行构建命令
```
php bin/satis build satis.json /var/www/satis
```
构建后检查生成的 /var/www/satis/packages.json，确认其中包含 "doctrine/inflector": {"2.0.4": {...}} 条目，且 dist 字段 URL 可被浏览器直接下载。

客户端正确引用
在业务项目的 composer.json 中，必须同时满足两项：

显式添加私有源：

"repositories": [{"type": "composer", "url": "https://packages.internal/"}]

禁用官方源回退：
```
"packagist.org": false
```

清理缓存后安装：

composer clear-cache && composer require doctrine/inflector:2.0.4

? 总结：何时用 `package`？何时用 `vcs`？

场景	推荐类型	原因
已有预编译 ZIP/TAR 包（如 Release 归档、CI 构建产物）	`"package"`	避免 Git 拉取、跳过版本解析，100% 控制内容与路径
需自动同步 Git 仓库最新 Tag/分支	`"vcs"`	利用 Satis 的自动发现能力，适合持续集成场景
混合模式（部分包 ZIP + 部分包 Git）	共存	`repositories` 是数组，可自由组合多种 `type`