不能只改 composer.json 就算完成依赖变更，因其仅声明意图，实际安装完全依赖 composer.lock 的精确快照；不运行 composer update，composer install 就忽略 json 修改、仍装旧版，导致 CI 与本地环境不一致。

composer.json 和 composer.lock 不是“两个配置文件”，而是两类不同职责的文件：一个声明意图，一个记录事实。

为什么不能只改 composer.json 就算完成依赖变更

改了 composer.json 只是告诉 Composer “我想用这些包”，但不触发实际安装或版本解析。比如把 "monolog/monolog": "^2.0" 改成 "^3.0"，composer.lock 里仍锁着 2.x 的版本，composer install 会照旧装旧版——除非你运行 composer update monolog/monolog 或 composer update，让 Composer 重新计算并写入新快照。

• 没运行 update 时，composer install 完全忽略 composer.json 的改动，只按 composer.lock 装
• CI 环境通常只跑 install，所以只提交 composer.json 修改而漏掉 composer.lock，会导致构建环境与本地不一致
• composer outdated 检查的是 composer.json 声明范围 vs packagist 最新版，但它不看 composer.lock 实际装了什么——可能显示“有更新”，但 lock 文件里已经是最新版

composer.lock 里哪些字段真正影响运行时行为

不是所有字段都值得盯。比对或审查时优先关注这几项：

Pandas 配置文件报告生成器

使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。

下载

• "name" 和 "version"：包名和精确版本，直接决定加载哪份代码
• "dist": {"shasum"}：压缩包哈希，校验下载完整性；同一版本若 shasum 不同，说明 dist 包被重发过（常见于 patch 修复）
• "require" 数组：该包自身依赖，影响自动加载顺序和类解析路径
• "platform" 下的 "php"、"ext-xxx"：平台约束，会改变依赖解析结果（如 PHP 8.2 下某些包会被跳过）
• 删掉 "packages-dev" 区块？别急——它虽不影响 composer install（默认不装 dev 包），但 composer install --dev 或本地开发时会用到，CI 若跑测试就依赖它

为什么 composer.json 没变，composer.lock 却大改

常见但容易被忽略的原因：

• 本地执行过 composer update 但没提交 composer.lock，下次别人拉代码后 composer install 就会按旧 lock 装，而你本地却已是新版本
• config.platform 在不同环境不一致：比如 CI 设了 "php": "8.2.0"，而你本地是 "8.1.25"，Composer 会为不同 PHP 版本选不同兼容包，导致 lock 文件大量差异
• 用了 path 类型仓库：本地 composer.json 里写了 "my/package": "dev-main"（path: "../my-package"），但生产环境没有这个路径，composer.lock 里就不会出现该条目——这种差异不会在 composer.json 中体现
• composer install --no-dev 不会删 packages-dev，但 composer update --no-dev 会清空它；如果某次 update 是带 --no-dev 运行的，lock 文件里就没了 dev 包，而 composer.json 里还写着

什么时候必须同时提交 composer.json 和 composer.lock

只要涉及依赖变更，就必须一起提交。典型场景包括：

• 新增、删除或修改 require / require-dev 中的包
• 调整版本约束（如从 "^2.0" 改成 "^3.0"）
• 修改 config.platform、minimum-stability 或 prefer-stable
• 升级 Composer 自身（v1 → v2）后运行 composer update --lock，plugin-api-version 字段会加入 lock 文件，必须提交

最常被忽略的是 platform 配置变更——它不改包列表，但会静默改变每个包的解析结果，且只体现在 composer.lock 里。