composer.json 不支持任何注释，必须用 scripts 或 extra 字段存放中文说明；scripts 可执行带上下文的提示命令，extra 适合存内部元信息，关键业务约束应外移至文档或 ci 脚本中。
composer.json 里不能写 // 注释，写了就报错
JSON 标准（RFC 8259）明确禁止注释，composer.json 是严格 JSON 文件，加 // 或 /* */ 会导致 json_decode() 直接失败，错误信息只会显示 JSON decode error: Syntax error，不指明哪一行——实际是解析器遇到第一个 / 就崩了。
常见踩坑点：
- VS Code 默认对
.json文件启用 JSONC（带注释的 JSON）模式，保存时悄悄插入注释，本地能“看着正常”，但 CI 流水线一跑就挂 - 用文本编辑器手动加中文注释后，
composer validate会直接失败，且不提示具体位置 - Git 合并冲突时，如果有人在带注释的版本上改，容易把非法字符一起合进去，后续所有人拉代码都 install 不了
用 scripts 字段写可执行的中文“活备注”
把说明文字转成带上下文的命令，既合法又能在需要时一键触发提醒。比如想标出某个开发专用包：
"scripts": {
"note-dev-only": "echo '⚠️ wpackagist-plugin/query-monitor 是调试用插件，上线前必须从 require 移除'"
}
执行 composer run note-dev-only 就能立刻看到中文提示。优势在于：
Pandas 配置文件报告生成器
下载
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
-
scripts是标准字段，完全合法，不会破坏任何解析流程 - 键名可自由命名（建议统一用
note-前缀），值支持任意 shell 命令，包括cat README-plugins.md这类读取外部文档的操作 - 比藏在 README 里更靠近依赖声明，新人执行
composer run就能看到所有备注 - Windows 用户注意：PowerShell 对单引号处理不同，跨平台项目统一用双引号包裹字符串
用 extra 存纯文本元信息，别塞进 description
description 字段只适合简短项目说明（建议 ≤120 字），会被 Packagist 显示、IDE hover 展示，但它不是“备注区”。真要存内部协作信息，extra 更合适：
"extra": {
"team-note": "advanced-custom-fields-pro 需单独购买 license，凭证存在 1Password 中「WP 插件」条目下",
"deploy-check": "此版本需配合 WP 6.5+，CI 脚本已加 version_check 步骤"
}
注意：
-
extra是 Composer 官方预留的扩展字段，类型为对象，不参与依赖解析，也不会被拒绝 - 不要往
description里堆砌长说明，它会被截断显示，且 IDE 只展示前半句 -
extra里的内容不会被任何标准工具自动读取或渲染，得靠团队约定——比如 CI 脚本里加jq -r '.extra."deploy-check"' composer.json提取检查项 - 避免和真实插件配置冲突，例如 Laravel 项目里
extra.laravel是框架专用，别往里面塞团队备注
真正起作用的中文协作，不在 composer.json 里
把关键上下文移出配置文件，放到更合适的地方：
- 在项目根目录维护一份
plugins-zh.md，对照列出：woocommerce→ 「电商核心功能，含支付网关与订单管理」 - 用
composer show查已装包后，结合wp plugin list --status=active（需 WP-CLI）交叉验证，避免路径错位导致“装了却看不到” - CI/CD 脚本中用中文日志输出（如
echo "✅ 正在部署「高级自定义字段」插件"），但执行命令仍是纯英文，不影响兼容性 - Git 提交时，在 commit message 里写清变更意图，比在配置里硬塞备注更可靠
最易被忽略的一点：多人协作时，composer.json 的修改常被当成“技术操作”跳过 Code Review，但其实它承载了大量业务约束和部署前提。把关键逻辑外移到文档或脚本中，反而更容易被看见、被讨论、被校验。
