Composer如何发布私有包到Satis_搭建企业内部Composer镜像站【高阶】

Satis是静态包仓库生成器而非镜像站；其“发布”本质是Satis拉取git仓库、解析tag、生成packages.json和ZIP包，需确保vcs仓库配置正确、tag符合语义化版本、项目配置指向Satis站点。

直接说结论：Satis 不是镜像站，而是静态包仓库生成器；发布私有包到 Satis 站点，本质是让 Satis 扫描你的 Git 仓库并生成 packages.json 和对应 ZIP 归档——不是「推送」，而是「拉取+生成」。

为什么 composer publish 不存在？

Satis 没有服务端 API，也不接受 http 推送。它只是一个命令行工具，运行时会：

• 克隆你配置的 Git 仓库（支持 git@、https://、甚至本地路径）
• 检出指定分支或标签（如 v1.2.0）
• 读取其中的 composer.json，提取 name、version、dist 下载地址等元数据
• 打包源码为 ZIP（可选），写入 dist 字段，并生成最终的 packages.json

所以「发布」= 提交带正确 version 的 tag + 触发 Satis 构建。别在本地跑 composer install 后试图上传 vendor —— Satis 不认这个。

satis.json 中必须配对的两个关键字段

很多人卡在构建后包不出现，问题常出在这两处没对齐：

• repositories 里每个仓库的 type 必须是 vcs（不是 package 或 composer）
• 每个 vcs 仓库的 url 必须能被 Satis 主机直接 git clone 通（比如填 git@gitlab.internal:php/my-utils.git，而非 https://gitlab.internal/php/my-utils —— 后者可能因无凭据失败）

示例片段：

{   "repositories": [     {       "type": "vcs",       "url": "git@gitlab.internal:php/my-utils.git"     }   ],   "require-all": true }

注意：require-all 表示拉取所有 tagged 版本；若只想要特定包，改用 "require": { "mycompany/my-utils": "*" }。

Git Tag 命名必须匹配 Composer 版本约束

Satis 只识别符合语义化版本规范的 tag，且默认忽略 dev- 开头的分支（除非显式配置 branches）。常见踩坑点：

• 打了 1.2 tag → 不生效（缺补零，应为 1.2.0）
• 打了 v1.2.0 tag → 生效（v 前缀被自动剥离）
• 打了 release/1.2.0 → 不生效（非 tag，是分支名）
• composer.json 里写 "version": "1.2.0" → 可以省略，Satis 优先从 tag 解析版本号

安全做法：打 tag 前删掉 composer.json 中的 version 字段，靠 Git tag 驱动版本，避免不一致。

构建后怎么让项目真正用上？

生成的 Satis 站点（比如 https://satis.internal）只是个静态文件目录，要让团队项目生效，必须在项目级或全局 composer.json 中声明仓库：

{   "repositories": [     {       "type": "composer",       "url": "https://satis.internal"     }   ],   "require": {     "mycompany/my-utils": "^1.2"   } }

关键细节：

• type 是 composer（不是 vcs），URL 指向 Satis 生成的 packages.json 所在根路径
• 首次使用前建议跑 composer clear-cache，否则 Composer 可能缓存旧的元数据
• 如果 Satis 站点启用了 HTTP Basic Auth，需提前执行 composer config http-basic.satis.internal username password

真正难的不是构建 Satis，而是确保 Git 权限、ssh 凭据、tag 规范、Composer 配置这四者严丝合缝——漏一环，包就「看不见」。