如何用Composer搭建私有仓库-composer-PHP中文网

Composer安装私有包失败主因是未正确配置私有源：repositories须顶层级、type必须为"vcs"、URL需含.git后缀或SSH格式；auth.json须放对路径且权限600；require包名须与私有库composer.json中name字段完全一致；Satis镜像需禁用packagist.org并确保URL以/结尾。

如何用composer搭建私有仓库

直接用 composer install 拉私有包失败，90% 不是网络或权限问题，而是你根本没让 Composer “看见”你的私有源——它默认只认 packagist.org，其他仓库必须显式声明、类型写对、fallback 关掉。

repositories 必须顶层级 + type: "vcs" 才生效

Composer 不会自动扫描 Git 地址，repositories 字段必须放在 composer.json 最外层，不能嵌在 config、scripts 或其他对象里。每项还得明确写 "type": "vcs"，写成 "git"、"package" 或留空都会被静默忽略。

✅ 正确写法：

{"repositories": [{"type": "vcs", "url": "https://gitlab.example.com/acme/utils.git"}]}

❌ 错误写法：URL 缺 .git 后缀（如 https://gitlab.example.com/acme/utils），会报 No valid composer.json was found
❌ 错误写法：用网页地址（https://gitlab.example.com/acme/utils/-/tree/main）代替可 git clone 的地址
SSH 格式也行："url": "git@gitlab.example.com:acme/utils.git"，但需确保运行用户已配好 SSH key

auth.json 放错位置 or 权限不对 = 认证静默失效

GitLab / GitHub 的 token 不是写进 composer.json，而是存进全局 auth.json。放错路径、权限太高、域名 key 不一致，Composer 都不报错，只当没这回事。

Linux/macOS 路径：~/.composer/auth.json（不是项目根目录）
Windows 路径：%APPDATA%\Composer\auth.json
权限必须是 600：chmod 600 ~/.composer/auth.json，否则直接跳过
GitLab 域名 key 必须和 URL host 完全一致："http-basic": {"gitlab.example.com": {...}}，不能带端口或协议
GitHub 用 github-oauth 字段，GitLab 用 http-basic，混用就失效

require 包名必须和私有库 composer.json 的 name 字段一字不差

Composer 不按 Git 路径匹配，只严格比对私有库自己 composer.json 里的 name 字段。差一个字符、大小写不对、vendor 段缺失，就报 Could not find package。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

假设私有库根目录 composer.json 写的是：{"name": "acme/utils", ...}
那主项目 require 就必须写："acme/utils": "dev-main"
❌ 不行："Acme/utils"、"acme-utils"、"utils"、"main"（缺 dev- 前缀）
分支名加 dev- 是强制的：dev-main 可行，main 或 * 会被当成模糊约束去 packagist.org 查

用 Satis 搭建静态镜像时，packagist.org 必须显式关掉

Satis 生成的是静态 packages.json 和 ZIP 文件，不提供 API。但如果你没在项目 composer.json 里关掉默认源，Composer 仍会优先查 packagist.org，导致“明明配置了却还是走外网”。

必须加这一行："packagist.org": false，且放在 repositories 同级
Satis 仓库 URL 必须以 / 结尾："url": "https://packages.internal/"，少斜杠会 404
packages.json 必须能被直接 GET 到：curl -I https://packages.internal/packages.json 返回 200
Satis 构建命令要指定输出目录：php bin/satis build satis.json web/，不是 web 或 web/.
satis.json 里 require-all 设为 true 才会收录所有分支；若设 require，得确保对应包的 composer.json 有合法 version 字段（不能是 dev-main）

最常被忽略的一点：Satis 不支持增量更新，每次 build 都是全量重刷。如果私有库频繁发版，得靠脚本定期触发构建，不能指望它自动感知变更。