composer.json文件如何编写_composer配置文件参数详解【入门】

require填运行时必需包如”guzzlehttp/guzzle”: “^7.5″，require-dev填开发用工具如”phpunit/phpunit”: “^10.0″；autoload需用psr-4严格匹配命名空间与路径，改后须执行composer dump-autoload。

require 和 require-dev 该填什么

这两个字段决定项目运行和开发时依赖哪些包，填错会导致 composer install 失败或运行时报 class not found。生产环境只装 require 里的包，require-dev 仅在本地开发或 CI 中生效。

常见错误：把 phpunit/phpunit 写进 require —— 它不该出现在线上；把 monolog/monolog 写进 require-dev —— 日志库是运行时必需的。

• require 填运行时真正需要的包，比如 "guzzlehttp/guzzle": "^7.5"、"laravel/framework": "^10.0"
• require-dev 填测试、构建、分析工具，比如 "phpunit/phpunit": "^10.0"、"friendsofphp/php-cs-fixer": "^3.14"
• 版本号推荐用 ^（兼容性更新）或 ~（补丁级更新），避免写死如 "1.2.3"，否则后续 composer update 不会升级

autoload 自动加载怎么配才不报错

PHP 找不到类，90% 是因为 autoload 没配对路径。Composer 不会自动扫描所有 .php 文件，必须显式声明命名空间与目录的映射关系。

最常用的是 psr-4，它要求目录结构严格匹配命名空间。比如你写了 Namespace appControllers;，那对应文件就得在 src/Controllers/ 下。

{     "autoload": {         "psr-4": {             "App\": "src/"         }     },     "autoload-dev": {         "psr-4": {             "App\Tests\": "tests/"         }     } }

注意：\ 是 jsON 里转义反斜杠，实际表示的是 PHP 命名空间分隔符 ；autoload-dev 只影响 composer dump-autoload --dev，测试类不会被生产环境加载。

• 改完 autoload 后必须运行 composer dump-autoload，否则新路径不生效
• 不要混用 psr-4 和 classmap 加载同一命名空间，容易冲突
• 如果项目没命名空间（老式 include 风格），用 files 字段，例如 "files": ["src/helpers.php"]

scripts 字段不是用来写 shell 脚本的

scripts 是 Composer 的钩子机制，本质是调用 php 函数或命令行工具，但它不是 shell 环境 —— 不支持管道 |、重定向 > 或变量展开 $PATH。

典型误用：写 "post-install-cmd": "php artisan key:generate | grep 'Application key set'" —— 这会直接报错，因为 Composer 不解析管道。

• 每个 script 条目应是一个完整可执行命令，例如 "post-autoload-dump": "Illuminate\Foundation\ComposerScripts::postAutoloadDump"
• 想串联多个操作？写个封装脚本（如 bin/deploy.sh），再在 scripts 里调用 "post-update-cmd": "bash bin/deploy.sh"
• 自定义 PHP 脚本需确保类存在且已 autoload，否则触发 Class 'XXX' not found

platform 和 config 的坑比想象中多

platform 用于声明当前运行环境“假装有”的扩展或 PHP 版本，常被用来绕过依赖检查；config 控制 Composer 自身行为，比如镜像源或超时时间。但它们极易引发隐性问题。

比如在 platform 里写 "ext-gd": "0"，会让 Composer 认为 GD 扩展已安装，但实际没装 —— 运行时调用 imagecreatefrompng() 就直接 Fatal Error。

• "platform": {"php": "8.1.0"} 适合 CI 构建时锁定 PHP 版本，但别在本地开发机上长期使用，会掩盖真实兼容性问题
• "config": {"fxp-asset": {"enabled": false}} 是旧版插件配置，Composer 2.x 已废弃，留着会警告
• 国内用户常加 "repositories": [{"type": "composer", "url": "https://packagist.phpcomposer.com"}]，但该镜像已停用，应换为 https://packagist.org 或阿里云源

复杂项目里，platform 和 config 往往是线上部署失败的第一排查点 —— 因为它们不报错，只悄悄改变行为。