composer中文镜像不生效的主因是配置格式错误：字段名必须为repositories.packagist.org，值为完整json对象，且url末尾必须带/；正确命令为两行分别设置type和url，缺一不可。

Composer中文镜像配置后仍走packagist.org？检查字段名和URL末尾斜杠

镜像不生效不是网络问题，而是 Composer 2.2+ 对配置格式极其敏感：字段名必须是 repositories.packagist.org（不是 repo.packagist 或 repos.packagist），值必须是完整 JSON 对象，且 url 字符串末尾必须带 /。

常见静默失败现象：
运行 composer install -vvv 仍看到 GET https://repo.packagist.org/packages.json；
composer config -g repositories.packagist.org.url 返回空或报错；
镜像 URL 写成 https://mirrors.aliyun.com/composer（缺末尾 /）→ 请求变成 /packages.json → 实际路径为 /composer/packages.json → 404。

• 正确写法（两行命令，不可合并）：
  composer config -g repositories.packagist.org.type composer
composer config -g repositories.packagist.org.url https://mirrors.aliyun.com/composer/
• 验证是否生效：composer diagnose 查看 Repo packagist.org: 行输出的域名是否为你配置的镜像地址
• CI 环境中务必显式执行这两条命令，全局配置不会自动继承

Git 拉取后 composer install 失败，提示 lock 文件过期

这不是镜像问题，而是 composer.lock 与 composer.json 不一致导致的校验拒绝——Composer 只允许用完全匹配的 lock 文件还原依赖。

典型诱因：
Git 合并时漏提交 composer.lock；
Windows/Linux 协作者因换行符差异使 Git 标记文件为 modified，但未实际更新内容；
CI 脚本误删 lock 文件却未重建。

• 先运行 composer validate：若提示 The lock file is not up to date，说明是“过期”，不是损坏
• 刚 git pull 完，且远程已有新 composer.lock？直接 git checkout -- composer.lock 拉回最新版，再 composer install
• 本地 composer.json 确实改了（如加了新包），又不想升级其他依赖？用 composer update --lock —— 它只重写 lock，不碰 vendor/，也不查远程

子模块项目里报 Could not find package，不是镜像缺包

这个错误根本没走到镜像请求环节。原因通常是子模块目录未初始化，导致 composer.json 不存在，Composer 连解析都跳过。

git-version-control

基于 Git 的 OpenClaw 系统配置变更版本控制。提供两项核心能力：（1）SAVE —— 在执行敏感操作前创建检查点……

下载

现象：
进入 vendor/xxx/package 执行 git status 报 fatal: not a git repository；
目录下为空，或只有 .git 文件夹但无 composer.json。

• 在项目根目录执行：git submodule update --init --recursive
• 确认子模块路径下有合法 composer.json（至少含 name 和 autoload）
• 子模块内镜像配置不继承父项目：需单独在子模块根目录运行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g）
• 长期方案：把镜像配置写进子模块自己的 composer.json 的 repositories 字段，可 Git 提交，团队一致

Git 合并冲突残留导致 composer.json 解析失败

只要文件里存在 、<code>=======、>>>>> origin/main 这类标记，JSON 就非法。Composer 不会告诉你哪一行出错，只会报模糊的 JSON decoding failed: Syntax error 或直接卡死。

别手动删标记、别对齐缩进、别“差不多就行”——结构已不可信，强行修复可能触发 content-hash 校验失败，导致 composer install 静默装错包。

• 先用 git status 确认 composer.json 在 Unmerged paths 下
• 直接丢弃冲突状态：git checkout --ours composer.json（取本地）或 git checkout --theirs composer.json（取远端）
• 立刻运行 composer validate --no-check-publish 验证，通过后再决定是否同步更新 composer.lock
• 注意：composer.lock 往往也受冲突影响，不能只修 composer.json 就跑 install

镜像配置、Git 工作流、子模块初始化、冲突清理——这四件事各自独立，但任何一个环节出错都会让 Composer 表现异常。它们之间没有隐式关联，也不会互相掩盖，只是开发者容易把现象归为“网络不好”或“Composer 抽风”。