composer.lock是带完整哈希校验的依赖快照，非配置文件，禁止手动编辑或拼接；改空格、删逗号均致校验失败，应通过composer update --lock重建，提交前须运行composer validate --strict验证。

composer.lock 文件不是配置文件，不能手动编辑或拼接

它本质是带完整哈希校验的二进制快照，哪怕改一个空格、删一个 trailing comma，composer install 就可能拒绝执行，或退化为 composer update 行为——这不是警告，是硬性校验失败。

常见错误现象：

• CI 日志显示 Lock file operations: 123 installs, 45 updates, 67 removals，但你只改了一个包版本 → 实际是 composer.lock 被意外修改或字段缺失
• 本地 composer install 成功，Docker 构建时报 Package foo/bar has a PHP requirement incompatible with your PHP version → platform 字段没同步，或被编辑器自动删了 trailing comma 导致 JSON 解析不全

实操建议：

Discussion Composer

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

下载

• 提交前必须运行 composer validate --strict 检查语法与完整性
• Git 配置禁用 auto-CRLF：git config core.autocrlf false，避免 Windows 编辑器污染换行符
• 禁止在 CI 脚本中运行 composer update --lock 后不提交——这等于把构建环境的偶然结果当成了权威快照

换镜像源后 vendor/ 目录不可复用，必须清空重装

镜像切换（比如从 https://packagist.org 切到 https://mirrors.aliyun.com/composer/）不改变 composer.lock 内容，但会改变下载路径、缓存行为和 vendor 产物结构。混用会导致类加载失败、符号链接失效、扩展编译产物错位。

为什么不能“保留 vendor + 换镜像 + 再 install”：

• vendor/autoload.php 是根据当前 lock 和平台生成的静态映射，镜像切换后若没重生成，可能引用已失效的 dist URL 或旧路径
• 本地开发包（"type": "path"）的符号链接指向原机器路径，在新机器上变成 dangling link
• 某些扩展（如 ext-protobuf）的编译产物写入 vendor/ 子目录，跨平台复制直接崩溃

实操建议：

• 每次镜像变更后，先运行 rm -rf vendor composer.lock，再 composer install
• Docker 构建中用多阶段：builder 阶段用完整镜像源 + --no-dev --optimize-autoloader，final 阶段只 COPY vendor/ 和代码，不带任何缓存
• CI 脚本加防护：检查 composer config --list | grep repositories 输出是否匹配预期镜像 URL，不匹配则 abort

元数据缓存刷新必须用 --refresh，不能靠 clear-cache 或 --no-cache 单独解决

镜像同步延迟的本质是 Composer 复用本地缓存的 packages.json（默认 15 分钟不过期），哪怕镜像站已上线新版本，它也看不到。此时 composer update vendor/package 会直接返回 “Nothing to install or update”。

关键点：

• composer update --refresh（Composer ≥ 2.5）强制丢弃所有 cache/repo/ 下的元数据文件，并从当前配置的镜像源重新下载最新 packages.json
• composer clear-cache 会清掉 ZIP 和元数据，但下次 update 仍会立刻重建并复用——除非你主动加 --refresh
• --no-cache 只跳过 ZIP 缓存解压，不影响元数据读取；不配合 clear-cache 或 --refresh，它不会触发新版本识别

验证是否真重下：

• 终端输出必须含 Downloading https://，且时间戳是当前秒级；否则仍是缓存兜底
• 执行 composer config -g repo.packagist 确保输出是你期望的镜像 URL（如 https://mirrors.tencent.com/composer/），否则 --refresh 会去错地方拉

Docker 构建中 vendor 的 COPY 必须原子化且验证关键文件存在

CI 或 Docker 构建时，vendor/ 不是普通目录，而是由 lock 文件 + 平台环境 + 镜像源共同决定的产物。COPY 前若缺少校验，极易导致运行时类找不到、autoload 失效、甚至静默降级。

容易被忽略的细节：

• composer.lock 必须完整提交，不能部分覆盖或手动 patch —— 它不是文本配置，是校验入口
• vendor/autoload.php 和 vendor/composer/installed.json 必须存在且可读，否则 autoloader 初始化失败
• 多阶段构建中，builder 阶段的 PHP 版本、扩展、平台字段（platform）必须与 final 阶段一致，否则 installed.json 中的依赖兼容性判断会出错

实操建议：

• final 阶段 COPY 后加校验命令：test -f vendor/autoload.php && test -s vendor/composer/installed.json || exit 1
• 避免在 Dockerfile 中用 RUN composer install —— 这会把构建环境的不确定性带入镜像
• 使用 composer install --no-dev --optimize-autoloader --classmap-authoritative 生成最小、最确定的 vendor 结构