Composer自定义仓库配置及包管理优化指南-composer-PHP中文网

自定义仓库不生效，根本原因是加了repositories数组后composer默认隐式关闭packagist.org但未显式声明其禁用状态，需在数组首位添加{"type":"composer","url":"https://packagist.org","packagist":false}；vcs类型url必须可git clone且含.git后缀，name字段须为两段式，版本写法须与git分支或tag严格匹配。

composer自定义仓库配置及包管理优化指南

自定义仓库不生效？先检查 packagist.org 是否被隐式关闭

只要你在 composer.json 里加了 repositories 数组，Composer 就会默认禁用隐式的 Packagist 源——但它不会报错，也不会提示你，结果就是 composer require myorg/internal-sdk 仍然去 Packagist 查，报 Could not find package。

必须显式声明 Packagist 为“已禁用但需保留”的状态：

在项目级 composer.json 的 repositories 数组最前面加一条：{"type": "composer", "url": "https://packagist.org", "packagist": false}
不要删掉 Packagist 条目，也不要只写 {"type": "composer", "url": "https://packagist.org"}（这仍会启用）
全局执行 composer config -g packagist false 虽然可行，但会影响所有项目，慎用

vcs 类型 URL 填错，Composer 会静默失败

"type": "vcs" 不是万能占位符，它对 URL 格式极其敏感。填错后 Composer 不报错、不提示，只在 require 时找不到包。

验证方式很简单：手动运行 git clone https://your-git-url.git，必须成功且返回的仓库根目录下有合法 composer.json，其中 "name" 字段必须是两段式（如 "myorg/sdk"）。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

URL 必须以 .git 结尾（https://gitlab.example.com/myorg/sdk.git ✅，https://gitlab.example.com/myorg/sdk ❌）
不能指向 HTML 页面（如 GitHub release 页面、GitLab tag 页面）
凭据不能拼在 URL 里（https://token:x-oauth-basic@github.com/... 已弃用），必须走 auth.json

require 时版本写法必须和 Git 仓库实际引用严格匹配

Git 仓库不靠 packages.json 提供版本列表，而是动态解析分支名、tag 名。所以 composer require 的版本字符串，必须真实存在且可解析。

dev-main → 要求仓库存在 main 分支，且该分支 composer.json 中 "version" 可为空（Composer 自动识别为 dev 版本）
v1.2.3 → 要求仓库有对应 tag（git tag v1.2.3），且该 tag 指向的 composer.json 中 "version" 字段值必须严格等于 "1.2.3"（注意引号和小数点）
dev-feature/x → 要求存在 feature/x 分支，且其 composer.json 中 "version" 为空或含 -dev 后缀

私有仓库元数据优化：优先级、压缩与缓存

光让包能装上还不够，生产级私有仓库还得考虑加载速度、索引效率和资源开销。

设 "priority": 100 确保你的私有源比 Packagist（默认 50）优先被查，避免兜底延迟
启用元数据压缩：在仓库配置中加 "options": {"metadata-url": "/p2/%package%.json"}，配合 composer/metadata-minifier 可减少约 40% 元数据体积
Satis 生成的静态仓库建议开启 "archive" 配置，用 tar 存档 + skip-dev，大幅降低安装时的网络和解压开销

最容易被忽略的是：vcs 类型的 URL 是否真能 git clone 成功，以及 composer.json 中 "name" 和 "version" 是否与 Git 引用完全对齐——这两点不满足，其他所有配置都白搭。