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 更难排查。
