Composer 要求 composer.json 必须声明 name、description、type、license 四个核心字段，缺一将导致包无法识别或安装失败；autoload 需正确配置 psr-4 命名空间与路径，避免混用类型；require 仅含运行时依赖，require-dev 仅用于开发环境。

Composer 通过 composer.json 文件定义扩展包的元数据，这是 Packagist 和其他 Composer 生态工具识别、安装、依赖解析和自动加载的基础。关键不是“写全”，而是“写对字段语义和约束条件”。

必须声明的四个核心字段

缺少任一都会导致包无法被正常识别或安装失败（例如在 Packagist 上提交时校验不通过）：

• "name"：格式为 "vendor/name"，必须小写、不含空格，且 vendor 需与 Packagist 账户名一致（如 "myorg/my-package"）
• "description"：纯字符串，不能为空，Packagist 列表页直接展示此字段
• "type"：非任意值，必须是官方注册类型之一（如 "library"、"wordpress-plugin"、"symfony-bundle"），影响安装路径和工具链行为
• "license"：推荐用 SPDX 标识符（如 "MIT"、"GPL-2.0-or-later"），若为私有包可填 "proprietary"

autoload 自动加载配置的常见误配

写错会导致类找不到（Class not found），但 composer install 不报错——因为 autoload 是运行时生效的。

• 用 "psr-4" 时，命名空间末尾必须带反斜杠（"MyOrg\\MyPackage\\"），路径值必须是相对于 composer.json 所在目录的相对路径（如 "src/"）
• 不要混用 "psr-4" 和 "classmap" 指向同一目录，会导致重复注册和性能损耗
• 若包含函数文件（非 class），需用 "files" 字段显式声明（如 ["src/helpers.php"]），否则不会自动加载

{
  "autoload": {
    "psr-4": {
      "MyOrg\\MyPackage\\": "src/"
    },
    "files": ["src/functions.php"]
  }
}

require 与 require-dev 的边界问题

错误归类会导致生产环境意外引入开发依赖（如测试框架），或 CI 环境缺失必需工具。

• "require" 中的包会在所有环境下安装，应只放**运行时必需**的依赖（如 "php": "^8.1"、"monolog/monolog": "^3.0"）
• "require-dev" 只在本地 composer install 或 composer update 时生效；CI 中若执行 composer install --no-dev，这些包将被跳过
• PHP 版本约束写在 "require" 下（如 "php": ">=8.1.0 ），不是 "require-dev" ——它决定能否安装，不是开发辅助

scripts 字段执行时机与权限陷阱

"scripts" 定义的命令（如 "post-install-cmd"）默认以当前用户权限运行，但实际行为受 Composer 运行上下文影响极大：

• "post-autoload-dump" 在每次 composer dump-autoload 后触发，适合生成代理类或缓存映射，但不能依赖尚未生成的 autoloader
• 脚本中调用 PHP 命令请用 php 而非 ./vendor/bin/php ——后者在全局安装 Composer 时可能不存在
• 避免在 "pre-install-cmd" 中修改 composer.json，可能导致依赖解析混乱（Composer 已读取原始内容）

{
  "scripts": {
    "post-autoload-dump": [
      "@php ./bin/generate-stubs.php"
    ]
  }
}

最常被忽略的是 "type" 字段的实际作用：它不仅用于 Packagist 分类，还决定插件是否介入安装流程（比如 "drupal-module" 类型会触发 Drupal 插件重定位文件）。写错类型，有时比写错 autoload 更难排查。

# php  # 字符串  # 标识符  # require  # 命名空间  # symfony  # 开发环境  # 工具  # wordpress  # composer  # json  # js  # word  # class