composer怎么使用Satis搭建私有源_composer私有仓库搭建【内网】

satis不是开箱即用的私有源服务，而是静态站点生成器，需手动执行bin/satis build生成packages.json，并通过web服务器暴露该文件路径供composer客户端访问。

为什么 satis 不是“装上就能用”的私有源工具

它本质是个静态站点生成器，不是运行时服务。你跑一次 bin/satis build，它就扫一遍 composer.json 里写的包，拉代码、打标签、生成一堆 packages.json 和压缩包链接——然后就结束了。没有后台进程，不监听端口，也不自动更新。

常见错误现象：composer require 报错 Could not find package xxx at any version，但你确认包已提交、tag 已打、satis.json 也写了；问题往往出在没重新 build，或者 web 服务器没正确暴露生成的 packages.json 路径。

• 必须手动触发 bin/satis build satis.json web/ 才会刷新元数据
• 生成的 web/packages.json 必须能被 curl -I http://your-internal-mirror/web/packages.json 访问到（HTTP 200）
• satis.json 中的 repositories 列表只影响本次 build 的扫描范围，不决定客户端怎么连你这个源

如何让内网项目真正从你的 Satis 源安装包

关键不在 Satis 怎么建，而在 Composer 客户端怎么配。Satis 生成的是一个标准 Packagist 兼容的静态源，所以客户端只需把 repositories 指向那个 packages.json 地址即可。

使用场景：公司内网 gitLab 私有仓库 + 本地 nginx 挂载 Satis 输出目录。

• 确保 Satis 输出目录（如 /var/www/satis/web）被 Nginx/apache 映射为 http://satis.internal/
• 项目根目录的 composer.json 加上：

  {     "repositories": [         {             "type": "composer",             "url": "http://satis.internal/"         }     ],     "require": {         "company/internal-sdk": "^1.2"     } }

• 不要加 "packagist.org": false 除非你真想完全禁用公网源——否则私有包找不到时 Composer 还会 fallback 到 packagist.org

satis.json 里最常写错的三个配置项

它们直接决定哪些包能进你的私有源、以什么形式存在、是否可被依赖解析。

• "name"：只是生成页面的标题，不影响功能；但若和 repositories.url 混淆，容易误以为这是源地址
• "output-dir"：必须是绝对路径或相对于 satis.json 的相对路径；写成 "./web" 在某些 CI 环境下会因工作目录不同而写错位置
• "repositories" 列表中每个 repo 的 "type" 值只能是 "vcs"、"package" 或 "composer"；写成 "git" 或 "github" 会导致 build 静默跳过该仓库

参数差异示例：VCS 类型必须带完整 Git URL（"https://git.internal/company/sdk.git"），不能只写路径；而 "package" 类型则需手动声明 "version" 和 "dist"，适合打包二进制或 ZIP 归档。

build 太慢？几个实际有效的提速手段

Satis 默认会对每个 VCS 包执行 git clone --mirror，尤其当私有 Git 服务器响应慢或网络不稳定时，卡住是常态。

• 用 --skip-errors 参数避免单个失败包中断整个 build（bin/satis build --skip-errors satis.json web/）
• 加 "archive": {"Directory": "dist", "format": "zip", "skip-dev": true} 可减少每次 install 时的解包开销，但首次 build 会更久
• 对稳定 tag 包，建议在 satis.json 中显式指定 "only-stable": true，跳过 dev 分支扫描
• 如果所有包都托管在同一个 gitlab 实例，启用 "gitlab-domains" 并填入域名，能让 Satis 复用 HTTP Basic Auth 凭据，避免反复弹认证

性能影响明显：未设 only-stable 时，一个含 20 个包的源可能耗时 6+ 分钟；加上后通常压到 90 秒内。但要注意——dev 分支变更不会自动进源，必须手动 trigger build。

最容易被忽略的是权限与缓存：Satis 进程需要对 Git 仓库有读权限，且默认不复用系统级 git 缓存；如果多个项目共用同一台构建机，建议在 ~/.gitconfig 中开启 core.precomposeUnicode 和 http.postBuffer，否则大仓库容易中途断连。