Composer.json支持中文注释的前提是UTF-8无BOM编码，否则json_decode()因BOM或非法字节直接报Syntax error；RFC 8259要求UTF-8，PHP解析器对BOM零容忍，常见诱因包括记事本默认带BOM、复制混入全角字符等。
Composer.json 支持中文注释，但前提是文件必须是 UTF-8 无 BOM 编码；一旦带 BOM 或用 GBK/UTF-8 with BOM 保存，composer install 就会直接报 JSON decode error: Syntax error，且错误位置常指向第一行——不是注释本身有问题，而是编码破坏了 JSON 结构。
为什么中文注释一加就报错
JSON 规范（RFC 8259）明确要求文本使用 UTF-8 编码，且不定义注释语法；但 Composer 实际解析时用的是 PHP 的 json_decode()，它对 BOM 敏感、对非法字节零容忍。常见诱因：
- 用 Windows 记事本保存 → 默认带 UTF-8 BOM，开头三个隐藏字节
EF BB BF让{变成无效字符 - 从网页复制示例 → 混入全角空格、中文引号或 Zero Width Space（U+200B）
- 编辑器未设为“UTF-8 without BOM” → VS Code 默认是，但 Sublime 或 Notepad++ 需手动选
- Git 提交后换行符 + 编码叠加 → 某些 CI 环境读取时触发二次解码失败
怎么安全地写中文注释
注释不能写在标准 JSON 字段里（JSON 本身不支持），但 Composer 允许在 composer.json 顶层对象外加自由字段，只要不和保留字段冲突。实操中推荐两种方式：
- 用非标准字段模拟注释：
"_comment": "这里是数据库连接配置说明"—— Composer 忽略未知字段，不影响功能，且中文安全 - 把说明写进
readme.md或项目 wiki，composer.json保持纯配置，靠文档而非注释承载语义 - 绝对不要用
//或/* */—— 这会让json_decode()直接失败，PHP 不支持 JSON 行注释
验证是否真安全：运行 composer validate --no-check-publish，它只校验结构合法性，不报错即说明编码和语法过关。
VS Code 和其他编辑器的编码设置要点
关键不是“能不能显示中文”，而是“保存时是否丢弃 BOM”。不同编辑器行为差异大：
- VS Code：右下角点击编码名 → 选
Save with Encoding→ 选UTF-8（不是UTF-8 with BOM） - Notepad++：菜单栏
编码 → 转为 UTF-8 无 BOM 格式，之后每次新建文件默认沿用 - Sublime Text：
File → Save with Encoding → UTF-8，需确认状态栏显示UTF-8且无BOM字样 - 命令行快速检测：
head -c 3 composer.json | xxd，输出含ef bb bf即有 BOM，需清理
真正容易被忽略的点
团队协作时，问题往往不出在“能不能写中文”，而出在“谁的编辑器悄悄加了 BOM”。即使你本地一切正常，CI 流水线用 git clone 拉下来的文件可能因 Git 配置（如 core.autocrlf）导致编码偏移；更隐蔽的是某些 IDE 插件（如某些 PHP 代码模板工具）会在保存时自动注入 BOM。最稳的做法是把 composer format 加进 pre-commit hook —— 它不删注释、不重排 key，但能强制统一缩进与编码一致性，顺便过滤掉非法字节。
