企业内部php服务、微服务共用sdk/中间件、交付型定制系统三类项目必须使用自定义composer仓库；小团队mvp或个人库优先采用vcs直连git更轻量。
哪些项目适合用自定义 Composer 仓库
不是所有项目都需要自定义仓库，但以下三类场景基本绕不开：
- 企业内部 PHP 服务（如订单中心、用户中台）——依赖大量未开源的
company/*包，且不能上packagist.org - 微服务架构下多个子项目共用一套 SDK 或中间件（如统一日志、鉴权、配置中心客户端）——需要集中托管、版本收敛、灰度发布
- 交付型项目（如给银行/政府定制系统）——客户要求所有依赖离线可审计，禁止任何外网源，连
packagist.org的元数据都不能碰
小团队做 MVP 或个人工具库？先别急着搭私有源。直接用 vcs 类型配 Git 地址更轻量，composer require 时指定 dev-main 或 v1.2.0 tag 就能拉下来。
Artifactory 仓库 URL 必须带 /api/composer/ 和末尾斜杠
这是最常被忽略的硬性路径规则。Artifactory 创建的仓库类型必须是原生 composer（不是 generic 或 remote），否则 composer install 会报 Invalid repository type 或静默跳过该源。
正确 URL 格式只有这一种：
https://artifactory.example.com/artifactory/api/composer/my-virtual-repo/
错例包括：
-
https://artifactory.example.com/artifactory/my-virtual-repo/—— 缺/api/composer/，返回 404 或空 JSON -
https://artifactory.example.com/artifactory/api/composer/my-virtual-repo—— 少末尾斜杠，部分 Artifactory 版本会重定向失败 -
https://artifactory.example.com/artifactory/repo-name/—— 用 generic 仓库伪装，packages.json结构不兼容，composer update直接卡死
"packagist.org": false 是开关，不是可选项
只要你在 composer.json 的 repositories 里加了自定义源，就必须显式关掉默认源。否则 Composer 仍会优先查 packagist.org，导致私有包根本不会被扫描——哪怕它确实存在，composer require company/internal-sdk 也会报 Could not find package。
正确写法（放在 repositories 数组最前面）：
{
"repositories": [
{
"type": "composer",
"url": "https://artifactory.example.com/artifactory/api/composer/my-virtual-repo/"
},
{
"type": "composer",
"url": "https://packagist.org",
"packagist": false
}
],
"packagist.org": false
}
注意两点：
-
"packagist.org": false是顶层字段，不是repositories里的子项 - 第二条
{"type":"composer","url":"https://packagist.org","packagist":false}是为了“显式兜底”，避免某些旧版 Composer 解析异常；不加也行，但加了更稳
私有包上传后不会自动生效，必须满足命名与结构约束
Artifactory 不会像 Packagist 那样爬取 Git 仓库或解析 ZIP。你上传一个 ZIP 文件，它就只是个文件——除非这个包严格符合 Composer 的发现协议。
两个硬性条件缺一不可：
- 包名必须是两段式，形如
company/sdk，不能是sdk或company-sdk；且必须和composer.json中的"name"字段完全一致 - 必须通过
composer publish命令上传（或调用 Artifactory REST API），不能直接 Web UI 上传 ZIP；否则元数据（packages.json）不会更新，composer search查不到，require也找不到
验证方式很简单：浏览器打开 https://artifactory.example.com/artifactory/api/composer/my-virtual-repo/packages.json，确认里面包含你刚上传的 company/sdk 条目，并且 versions 下有对应版本号。
