需在composer.json中配置repositories并禁用packagist.org：将{"type":"composer","url":"https://your-private-repo.com"}置于repositories数组首位，且必须添加"packagist.org":false；否则composer仍会回退至公网源。
怎么让 composer install 从私有仓库拉包，而不是 packagist.org？
核心是改 composer.json 的 repositories 配置，把默认的 packagist.org 关掉，再加你的私有源。不关默认源的话，Composer 会先去公网找——哪怕你写了私有地址，它也可能绕过你直接连外网。
实操建议：
本文档主要讲述的是使用Nexus搭建Maven私服；私服是架设在局域网的一种特殊的远程仓库，目的是代理远程仓库及部署第三方构件。有了私服之后，当 Maven 需要下载构件时，直接请求私服，私服上存在则下载到本地仓库；否则，私服请求外部的远程仓库，将构件下载到私服，再提供给本地仓库下载。感兴趣的朋友可以过来看看
- 在项目根目录的
composer.json里，用"repositories": [{"type": "composer", "url": "https://your-private-repo.com"}]声明私有源 - 必须加上
"packagist.org": false（放在repositories数组最前面或单独设为对象），否则私有源只是“补充”，不是“替代” - 如果私有源需要认证，得提前运行
composer config -g http-basic.your-private-repo.com username token，不然install会卡在 401 - 私有源的
packages.json必须符合 Composer 的仓库协议格式，不能只是个放 zip 的静态目录
私有 Git 仓库（如 GitLab）怎么被 Composer 正确识别？
Composer 不直接 clone Git 仓库，而是靠解析 composer.json 文件来确定包信息。如果你把 composer.json 放在 Git 仓库根目录，就得告诉 Composer：“这个 Git 地址对应一个包”，靠的是 package 类型仓库 + 手动声明版本和 dist 源。
常见错误现象：运行 composer require vendor/name 报错 Could not find package vendor/name at any version，其实是没在 repositories 里写清楚包名、版本、dist 地址。
实操建议：
- 用
{"type": "package", "package": {"name": "vendor/name", "version": "dev-main", "source": {"url": "https://gitlab.example.com/vendor/name.git", "type": "git", "reference": "main"}}} -
source.url必须是可被git clone的地址；reference要写分支或 tag 名，不能写HEAD - 这种写法适合单个包临时接入，不适合大量包——维护成本高，且无法自动发现新版本
composer config --global repositories. 和项目级 repositories 有什么区别？
全局配置影响所有项目，项目级只影响当前目录下的 composer.json。但很多人以为设了全局就一劳永逸，结果发现某些项目还是连公网——因为项目自己的 composer.json 里写了 "repositories": [{"packagist.org": true}]，覆盖了全局设置。
性能与兼容性影响：
- 全局配置对 CI/CD 不友好：不同项目可能依赖不同私有源，硬编码到全局容易冲突
- 项目级更可控，但每次 init 新项目都要手动配；可以用
composer create-project模板规避 - Composer 2.2+ 开始支持
composer.json里的repositories数组顺序决定优先级，排第一的源最先被查
为什么 composer update 还是去连 packagist.org？
最常踩的坑：只改了 repositories，但没删掉 vendor/ 或清缓存。Composer 本地缓存（~/.composer/cache）里还存着旧的 packagist.org 元数据，update 时会复用，导致看似“没生效”。
实操建议：
- 执行
composer clear-cache再试 - 删掉
vendor/和composer.lock，重新composer install - 加
-vvv参数看详细日志：composer install -vvv 2>&1 | grep -i "repo\|http"，确认实际请求的 URL 是不是你的私有地址 - 私有源返回 500 或超时，Composer 默认静默 fallback 到 packagist.org——要关掉 fallback，必须显式禁用
packagist.org
私有仓库最关键的不是“能不能连上”，而是“包元数据是否完整、签名是否可信、镜像同步是否及时”。很多团队卡在第一步，其实问题出在私有源服务本身没正确暴露 packages.json 或没处理好 HTTP 缓存头。
