本文详解如何在 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
|
Satis 的本质是“静态元数据生成器”，而非运行时服务。package 模式正是其轻量特性的集中体现：不依赖 Git、不执行脚本、不解析 composer.json，仅靠 JSON 描述即可完成企业级包分发——这对离线环境、安全审计、合规发布尤为关键。
