Composer PHP内网仓库搭建_Composer私有库管理方案【进阶】-composer-PHP中文网

私有仓库需在项目根目录composer.json中显式声明repositories字段；凭据必须通过权限为600的auth.json配置；satis需手动build且tag须符合语义化版本。

composer php内网仓库搭建_composer私有库管理方案【进阶】

私有仓库必须在项目 composer.json 里显式声明

Composer 不会自动扫描你内网的 Git 服务器或本地目录，composer require vendor/package 报 Could not find package 的第一原因，就是项目根目录的 composer.json 没配 repositories 字段。

常见错误包括：

只改了私有包自己 composer.json 里的 name，却没在使用它的项目里加仓库声明
误以为配置过 composer config --global 就全局生效——它只影响插件和部分 config 项，repositories 是纯项目级配置
把仓库地址写进子目录的 composer.json（比如 packages/foo/composer.json），Composer 完全不读那里

正确做法：在项目根目录 composer.json 的顶层加：

"repositories": [
  {
    "type": "composer",
    "url": "https://packages.internal.company"
  }
]

注意：type: "composer" 表示指向一个已部署的 Satis 或 Private Packagist 服务；若直接连 Git，才用 type: "vcs"。

auth.json 是唯一合法的凭据载体，权限必须是 600

HTTP Basic Auth、GitLab/GitHub OAuth token、甚至 SSH 密钥路径，都只能通过 auth.json 注入，且文件位置仅限两处：项目根目录，或用户家目录（~/.composer/auth.json）。

不这么做会直接失败：

btpanel phpsite 宝塔面板PHP网站

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

下载

把用户名密码硬写进 composer.json —— 提交即泄露，CI 环境更危险
用 composer config http-basic.repo.internal.com user pass 写进全局 config —— 多项目混用同一账号时权限失控
auth.json 权限不是 600（Linux/macOS）—— Composer 会静默忽略，报错却是 Authentication failed

典型 auth.json 结构：

{
  "http-basic": {
    "packages.internal.company": {
      "username": "deploy",
      "password": "xxx"
    }
  },
  "github-oauth": {
    "github.com": "ghp_xxx"
  }
}

Satis build 后 packages.json 才生效，不是实时同步

Satis 不是代理服务，它生成的是静态文件。你 push 了新 tag 或改了私有包的 composer.json，Satis 不会自动感知——必须手动运行 php bin/satis build satis.json web/。

容易漏掉的关键点：

build 命令必须在 Satis 项目根目录执行，否则找不到 satis.json 或权限出错
satis.json 中的 repositories 列表要包含目标 Git 地址，且协议得匹配（例如用 https:// 而非 git@，除非你配了 ssh2 选项）
新 tag 必须符合语义化版本（如 v1.2.3），否则 Satis 默认不收录；想收 dev-feature 分支，得加 "require-dependencies": true
build 完后，确认 https://packages.internal.company/packages.json 能被 curl -I 访问到，状态码是 200

require 时版本号必须对应 Git tag，不是 composer.json 里的 version

对于 type: "vcs" 仓库，Composer 完全忽略私有包自身 composer.json 中的 version 字段，只认 Git tag。

典型翻车现场：

打了 tag 1.0，但没加 v 前缀 → 正确应为 v1.0.0 或 1.0.0
require 写 "vendor/pkg": "^1.0"，但 Git 只有 dev-main 分支 → 必须设 "minimum-stability": "dev"，并写成 "dev-main"
强制推送覆盖已有 tag（git push --force --tags）→ Composer 缓存可能仍拉旧 commit，必须 composer clear-cache