Composer.json如何实现注释效果？非标字段使用与镜像【科普】-composer-PHP中文网

composer.json不支持//或/ /注释，因json标准禁止注释；可用_comment等非标字段“伪注释”，但仅作说明不参与解析，且需避免与config、extra等保留前缀冲突。

composer.json如何实现注释效果？非标字段使用与镜像【科普】

Composer.json 里不能写 // 注释，但可以用非标字段“假装注释”

JSON 标准本身不支持注释，composer.json 是严格遵循 JSON 规范的配置文件，直接写 // 或 /* */ 会导致 composer install 报错：JSON decode error: Syntax error。官方明确拒绝支持注释（见 Composer GitHub issue #271），所以别试了。

可行的“伪注释”方式是利用 Composer 对未知字段的宽容性：只要字段名不是 name、require、autoload 等保留键，它会忽略——你可以用 _comment、__note 甚至 FIXME 这类自定义字段存说明文字：

{
  "name": "my/app",
  "require": { "php": "^8.1" },
  "_comment": "以下包仅用于开发环境，CI 会跳过安装",
  "require-dev": {
    "phpunit/phpunit": "^10.0"
  }
}

注意：_comment 不会被 Composer 解析，也不会影响依赖解析或 autoload 生成，但它能被 IDE 高亮显示（部分支持 JSON Schema 的编辑器可识别为字符串字段），且 git diff 里可见。

非标字段命名要避开 Composer 内部保留前缀

虽然 Composer 忽略未知字段，但某些前缀有潜在风险：

config. 开头的字段（如 config.extra）会被 Composer 解析为配置项，可能触发意外行为
extra. 是合法的 Composer 扩展字段，用于传参给插件，别和它撞名（比如不要叫 extra_comment）
scripts.、autoload.、repositories. 等顶层保留字段名绝对不能复用
推荐用全小写加下划线，如 _notes、_todo、_deprecated_since，避免驼峰或中划线（部分旧版 Composer 对非字母数字+下划线字段处理不稳定）

镜像配置写在 config.repositories 里，不是注释场景

镜像（如阿里云、华为云）是真实生效的配置，必须走标准路径：config.repositories 或全局 ~/.composer/config.json。常见错误是把镜像 URL 塞进注释字段里，结果镜像根本不起作用：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

✘ 错误写法（注释字段里藏镜像，无效）：

{
  "_mirror_url": "https://mirrors.aliyun.com/composer/",
  "require": { "monolog/monolog": "^2.0" }
}

✔ 正确写法（显式声明仓库）：

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://mirrors.aliyun.com/composer/"
    }
  ],
  "require": { "monolog/monolog": "^2.0" }
}

注意：repositories 是数组，多个镜像需按优先级从上到下排列；若只配国内镜像，建议同时保留 packagist.org 作为 fallback（设 "packagist.org": false 关闭默认源，再手动加镜像）。