本文详解如何在 Satis 配置中跳过 Git 全量拉取，直接通过 type: "package" 声明本地或远程 ZIP 归档包，实现对特定版本的精准收录，避免冗余下载与构建失败。
本文详解如何在 satis 配置中跳过 git 全量拉取，直接通过 type: "package" 声明本地或远程 zip 归档包，实现对特定版本的精准收录，避免冗余下载与构建失败。
Satis 默认通过 "type": "vcs"（如 Git）拉取整个仓库，并基于其 composer.json 和 Git 标签/分支推导所有可用版本——这虽适合长期维护的私有组件库，但在需要快速集成第三方已发布 ZIP 包（如 GitHub Release 下载的 xxx.zip）或仅引入某一个稳定版而无需源码历史的场景下，反而造成构建缓慢、磁盘占用高、甚至因权限/网络问题失败。
此时，应改用 "type": "package" 模式：它不依赖 VCS 协议，而是由你显式定义包名、版本号及 dist 归档地址，Satis 将直接将其作为独立条目写入生成的 packages.json，跳过任何 Git 克隆、解析或版本探测流程。
✅ 正确配置语法（支持本地 ZIP 与远程 ZIP）
以下是一个生产就绪的 satis.json 片段，混合使用了 Git 仓库（Laravel）和本地 ZIP 包（Doctrine Inflector v2.0.4）：
Evez Github Manager
下载
在 OpenClaw 中管理 GitHub 仓库、Pull Request、Issue 与工作流。适用于审查 PR、管理 Issue、自动化 GitHub Actions、同步仓库等场景。
{
"name": "企业内部包仓库",
"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": {
"doctrine/inflector": "2.0.4",
"laravel/laravel": "dev-main"
},
"output-dir": "/var/www/satis",
"archive": {
"directory": "dist",
"format": "zip",
"skip-dev": true
}
}
? 关键要点说明：
repositories中每个"type": "package"条目必须包裹在"package"键下，且该对象需包含完整元数据（name、version、dist是必填项）；dist.url必须是 Web 可公开访问的绝对 URL（如https://packages.internal/dist/xxx.zip），不能写本地路径（如C:/...或/tmp/xxx.zip）——Satis 构建时不会复制 ZIP 文件，它只记录链接；你需提前将 ZIP 上传至 Web 服务器对应路径；require字段必须显式声明该包及其版本（如"doctrine/inflector": "2.0.4"），否则 Satis 不会将其纳入最终仓库；- ❌ 禁止与
"require-all": true共存：二者逻辑冲突，"require-all"会覆盖require并尝试扫描所有 VCS 仓库，导致 ZIP 包被忽略；- 若 ZIP 内结构不符合 PSR-4 自动加载规范，请务必补全
autoload字段，否则 Composer 安装后无法自动加载类。
⚠️ 注意事项与常见陷阱
| 问题 | 原因 | 解决方案 |
|---|---|---|
packages.json 中无该包 |
require 未声明，或 version 格式非法（如含空格、v2.0.4 应写为 2.0.4） |
使用 composer validate 检查 ZIP 内嵌的 composer.json；确保 satis.json 中 require 的版本字符串与 package.version 完全一致
|
composer install 报 Could not find package ...
|
客户端 composer.json 未正确配置私有源，或未禁用 packagist.org
|
客户端必须设置："repositories": [{"type":"composer","url":"https://packages.internal/"}]"packagist.org": false⚠️ URL 末尾必须带 /，否则 Composer 请求 https://packages.internal/packages.json 会 404 |
| ZIP 下载失败（403/404） |
dist.url 路径不可达、Web 服务器未配置 MIME 类型或目录权限不足 |
Nginx 示例配置：location ~ .zip$ { add_header Content-Type application/zip; }确认 ZIP 文件实际存在于 output-dir/dist/ 对应 URL 路径下 |
✅ 总结：何时选择 type: "package"？
- ✅ 你已有现成的 ZIP/TAR 归档（如 GitHub Release、CI 构建产物）；
- ✅ 你只需某个固定版本，无需跟踪上游 Git 更新；
- ✅ 你希望规避 Git 权限、SSH 密钥、网络代理等 VCS 相关复杂性；
- ✅ 你需要对归档内容做定制化处理（如剔除测试文件、注入配置）。
? 提示：对于高频更新的内部组件，仍推荐使用
"type": "vcs"+require精确版本；而"package"模式更适合“快照式”引入第三方稳定版或离线环境兜底分发。两者可共存于同一satis.json，由require统一调度，灵活兼顾效率与可控性。
