Composer镜像配置全攻略_零基础学会源地址修改-composer-PHP中文网

配 composer 镜像必须严格遵循三要素：键名 repo.packagist、type 值 composer、url 以 / 结尾，缺一不可；项目级需写入 composer.json 的 repositories 数组首位并禁用 packagist.org，且须删除 vendor 和 composer.lock 后重装才生效。

composer镜像配置全攻略_零基础学会源地址修改

配 Composer 镜像不是改个 URL 就能加速，不按规范写，composer install 依然连 packagist.org、卡在 Resolving dependencies、甚至静默走官方源——连报错都没有。

composer config -g repo.packagist 命令必须带全三要素

这条命令是全局换源最快的方式，但漏掉任意一个，配置就白写，且不提示错误：

repo.packagist 是唯一有效键名：写成 repos.packagist（多 s）、mirror 或大小写混用（如 Repo.Packagist）都会被忽略
composer 是强制 type 值：不能省略，也不能写成 vcs、package 或空字符串
镜像 URL 必须以 / 结尾：比如 https://mirrors.aliyun.com/composer/ ✅，少斜杠会拼出 /composerpackages.json 导致 404 或 fallback 到官方源

正确执行：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

验证是否生效：

composer config -g repo.packagist

输出应为完整 JSON：{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}。如果为空、null 或报错，说明没写对。

项目级配置必须写进 composer.json 的 repositories 数组首位

项目级镜像只对当前项目起作用，但结构要求极严，写错位置或格式就会被完全忽略：

必须放在项目根目录的 composer.json 中，写进 composer.lock 或全局 config.json 无效
repositories 必须是数组（[]），不能是对象（{}）；阿里云镜像对象必须是数组第一个元素
必须显式禁用官方源：{"packagist.org": false} 是独立对象，要和镜像对象并列放在 repositories 数组里，不能嵌套、不能合并

错误示例（会被忽略）：

Discussion Composer

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

下载

"repositories": {"packagist": {"type": "composer", "url": ""}}

正确结构（以阿里云为例）：

"repositories": [
  {
    "type": "composer",
    "url": "https://mirrors.aliyun.com/composer/"
  },
  {
    "packagist.org": false
  }
]

改完镜像后 vendor 和 composer.lock 必须删干净再 install

Composer 不会重新解析已存在的 composer.lock —— 它照着 lock 文件里的 dist.url 直接下载，根本不管 repositories 配了啥：

只跑 composer update 没用：它可能沿用旧 lock 里的官方 URL，镜像形同虚设
必须手动删除 vendor/ 和 composer.lock，再执行 composer install
CI/CD 环境尤其要注意：缓存的 composer.lock 会让流水线持续走错源，得加 rm -rf vendor composer.lock 步骤

提速验证方式：加 -vvv 参数运行 composer install -vvv，日志中出现 Downloading https://mirrors.aliyun.com/... 才算真正生效。

全局配置在宝塔、CI、systemd 等场景下常不生效

composer config -g 写的是当前用户的 ~/.composer/config.json（Linux/macOS）或 %APPDATA%\Composer\config.json（Windows）。但在以下环境里，实际执行命令的用户往往不是你：

宝塔面板「PHP 管理器」里一键部署，实际是 www 用户执行
Jenkins 流水线默认用 jenkins 用户
systemd 服务常用 root 或专用服务账户

排查方法：

用目标用户身份登录 shell，再执行 composer config -g repo.packagist 查输出
CI 脚本中不要依赖全局配置，改用临时参数：composer install -vvv --repository-url=https://mirrors.aliyun.com/composer/

项目级配置比全局更可靠——它可 Git 跟踪、不受执行用户影响、也不会被其他项目干扰。首次配置建议优先用项目级，确认生效后再决定是否补全局。