PHP项目中使用Composer配合Satis搭建企业级私有包仓库-composer-PHP中文网

根本原因在于satis.json未正确配置require或require-all，导致包未被索引入packages.json；satis仅处理显式声明的包和版本，不自动扫描仓库，且需配合nginx/apache正确托管、url以/结尾、项目级composer.json声明私有源并禁用packagist.org。

php项目中使用composer配合satis搭建企业级私有包仓库

satis.json 里 require-all 或 require 写不对，包就根本不会进索引

绝大多数“composer install 找不到私有包”的问题，根源不是网络或权限，而是 satis.json 没真正把包纳入索引。Satis 不会扫描 Git 仓库所有分支或 tag —— 它只认你明确写进 require 或 require-all 的内容。

"require-all": true：拉取 repositories 列表中每个 VCS 仓库的所有合法 tag（如 v1.0.0、2.3.1）和 stable 分支（如 main、master），但默认跳过 dev- 前缀分支；如需包含，得加 "skip-dev": false
"require": { "vendor/package": "*" }：只匹配该包的语义化版本 tag（如 v1.2.0）；若仓库没打任何 tag，这个包就静默消失
如果用了 "type": "vcs" 但没在 require 或 require-all 中声明，Satis 构建时完全跳过，不报错也不生成元数据
Git 仓库根目录下必须有合法 composer.json，且 name 字段必须全小写 + 短横线（如 acme/utils），含非法字符或大小写混用会导致解析失败、包被丢弃

Web 服务器没配对，packages.json 就是 404 或 MIME 错误

Satis 只生成静态文件，不提供 HTTP 服务。Nginx/Apache 配置错一个细节，composer install 就会卡在 “Could not fetch” 或 “Invalid response body”。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

root 必须精确指向 satis.json 中的 output-dir 值（如 /var/www/satis/web），不能多一层或少一层
Nginx 必须显式声明 JSON MIME 类型：types { application/json json; }，否则返回 text/plain，Composer 直接拒绝解析
URL 必须以 / 结尾（如 "url": "https://pkg.internal/"），否则 Composer 拼路径时变成 packages.json/ 导致 404
访问 curl -I https://pkg.internal/packages.json 应返回 HTTP/2 200 + Content-Type: application/json；缺一不可

dist ZIP 下载失败，其实是 Web 服务器没放行 dist 路径或 MIME 不对

想让 composer install --prefer-dist 真正走 ZIP 下载而非回退到 git clone，光在 satis.json 开 archive 还不够。

archive 配置必须启用："archive": { "format": "zip", "skip-dev": true, "directory": "dist" }
生成的 ZIP 路径形如 dist/vendor-package/1.0.0-hash.zip，Nginx/Apache 必须允许该路径被公开访问（无 rewrite 截断、无 403）
curl -I https://pkg.internal/dist/vendor-package/1.0.0-hash.zip 必须返回 Content-Type: application/zip；否则 Composer 或浏览器可能拒绝下载
若仍 fallback 到 source，运行 composer install -v 看具体提示——常见原因是 ZIP 404，或 packages.json 里 dist.url 字段拼错了（比如少了个 /）

客户端 composer.json 配置顺序和 packagist.org 开关没设对，私有源就无效

即使 Satis 服务完全正常，项目里不改配置，Composer 还是优先去 Packagist 找包，结果报 Could not find package。

必须在项目顶层 composer.json 的 repositories 数组里声明私有源，type 必须是 "composer"，不是 "vcs" 或 "package"
私有源 URL 必须可被 curl 直接访问到 packages.json，且返回状态码 200、Content-Type 正确
必须显式禁用 Packagist 回退："packagist.org": false 放在 repositories 同级的 config 块里，否则 Composer 仍会尝试查官方源
全局配置（composer config -g）虽方便，但易被 CI 环境覆盖或与项目级冲突；推荐优先用项目级配置，更可控、可审计