如何利用Composer管理私有PHP组件？基于Satis的内部库搭建-composer-PHP中文网

私有包require不到，90%是仓库未在项目composer.json中声明；必须在项目根目录composer.json顶层显式配置repositories数组，type为"composer"，url指向satis输出目录根路径（如https://packages.internal/web/），且末尾带斜杠。

如何利用composer管理私有php组件？基于satis的内部库搭建

私有包 require 不到，90% 是仓库没在项目 composer.json 里声明

Composer 不会自动发现你内网的 Git 服务器或 Satis 服务——它只读项目根目录 composer.json 中的 repositories 字段。全局配置 composer config --global repositories.xxx 对依赖解析完全无效。

必须在项目级 composer.json 顶层显式写入：

"repositories": [
  {
    "type": "composer",
    "url": "https://packages.internal/"
  }
],
"minimum-stability": "stable",
"prefer-stable": true

注意三点：

url 必须指向 Satis 输出目录的根路径（比如 web/），且末尾带斜杠；如果 Satis 构建命令是 php bin/satis build satis.json web/，那 URL 就得是 https://packages.internal/web/
type 必须是 "composer"，不是 "vcs" 或空字符串；配成 vcs 会导致 Composer 去直接 clone，绕过 Satis 元数据
删掉 "packagist.org": false 以外的其他禁用逻辑，否则可能意外 fallback 到公网源

satis build 成功但 packages.json 里没包，大概率是 tag 或分支不匹配

Satis 默认只收录语义化版本 tag（如 v1.2.0）和 master 分支。它不扫描未打 tag 的提交，也不认 dev-main、1.2.0-rc1 这类非标准格式。

btpanel phpsite 宝塔面板PHP网站

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

下载

检查并操作以下项：

进私有包 Git 仓库，确认已执行 git tag v1.0.0 && git push --tags；没 tag 就没有元数据
若想支持无 v 前缀的 tag（如 1.2.0），在 satis.json 加字段："version-regex": "[v]?[0-9]+(?:\.[0-9]+)*"
若要拉 dev-main，需同时设 "minimum-stability": "dev" 和 "prefer-stable": false，并在 satis.json 中改用 "require": {"vendor/name": "dev-main"}，require-all 对开发分支无效
确保私有包的 composer.json 里 name 字段（如 "acme/sdk"）和你在项目中 composer require acme/sdk 写的一致，大小写敏感

构建失败常见于权限、网络或 MIME 配置错误

执行 php bin/satis build satis.json web/ 报错，多数卡在 Git 拉取或响应解析环节：

Could not clone https://git.internal/repo：Satis 进程用户（如 www-data）没配 Git 凭据；HTTPS 私仓需在该用户家目录下放 ~/.composer/auth.json，含对应 token；SSH 私仓需把 id_rsa 放进 ~/.ssh/ 并 chmod 600
Could not parse version constraint dev-main：私有包自己的 composer.json 里写了 "version": "dev-main"，必须删掉该行，让 Composer 从 tag 推断版本
packages.json 返回 404 或内容为空：Nginx/Apache 未启用 .json MIME 类型；加配置 types { application/json json; }，并确认 add_header Content-Type application/json; 已生效
磁盘空间不足或 output-dir 无写权限：Satis 会临时克隆所有仓库，包多时极易爆满

dist 下载失败回退 source，通常 ZIP 没生成或 CDN 域名不对

如果你启用了 archive 配置，但 composer install 仍走 source（即 clone Git），说明 dist 文件链路断了。

关键点：

satis.json 中 "archive": {"directory": "dist", "format": "zip", "prefix-url": "https://cdn.internal/dist/"} —— prefix-url 必须可被客户端直接访问，且返回 200
检查 web/dist/ 目录下是否真有对应 ZIP 文件；Satis 默认只对 stable tag 打包，dev 分支不会生成 dist
确保 Web 服务器能正确路由到 dist/ 子目录，Nginx 示例：location /dist/ { alias /path/to/web/dist/; }
别忽略 HTTPS 证书问题：内网自签名证书会导致 curl 能通但 Composer 拒绝下载，需在 PHP 的 openssl.cafile 指向可信 CA 包

Satis 的核心限制在于它不提供服务，只生成静态文件；每次代码变更后必须手动或定时 build，这点容易被当成“部署完成就一劳永逸”而忽略。真正上线前，务必用 curl -I https://packages.internal/packages.json 和 composer clear-cache && composer update -vvv 双验证。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！