Composer 仅管理 PHP 后端依赖，不处理前端 SPA 构建；type 应据用途选 "library"（可复用 API 包）或 "project"（独立 API 服务）；autoload 不得包含前端文件，require-dev 须配合 --no-dev 避免污染生产环境。
Composer 本身不管理前端单页应用（SPA）的代码或构建流程，它只负责 PHP 后端依赖。所谓“大型单页面应用的后台集成”，本质是：PHP 作为 API 服务端，与前端 SPA 分离部署，而 Composer 仅承担后端服务的依赖管理、自动加载、包隔离与本地开发协同任务。
composer.json 必须声明为 type: "library" 还是 "project"？
取决于你如何组织代码结构：
- 如果你的 PHP 后端是一个独立可复用的服务（比如
acme/user-api），被其他项目 require，那就必须设"type": "library"，并提供autoload规则； - 如果你只是用 PHP 搭一个配套的 API 服务器（如 Laravel 或 Slim 应用），不打算被其他 Composer 包引用，那就用默认的
"type": "project"—— 它允许你定义scripts（比如"post-install-cmd"触发前端构建）、不强制要求name字段，也更符合实际部署习惯。
错误做法是：在纯 API 项目里硬写 "type": "library" 却没配 autoload，结果导致 vendor/autoload.php 加载不到自己的类；或者反过来，在要发布为 SDK 的包里漏掉 type，导致 Packagist 拒绝收录。
如何让 PHP 后端自动加载前端构建产物（如 dist/ 静态文件）？
Composer 不处理静态资源路径，但你可以用它触发构建并约定目录结构：
立即学习“PHP免费学习笔记（深入）”；
- 在根目录
composer.json的"scripts"中加入："post-install-cmd": ["npm ci --prefix ./frontend && npm run build --prefix ./frontend"]
- 确保前端构建输出到
./public/dist/（Laravel）或./public/build/（Symfony），PHP 路由直接readfile()或 Nginx 静态映射即可； - 不要把
node_modules或src/放进autoload—— 这会导致 Composer dump-autoload 失败或污染自动加载器。
常见坑：在 autoload 里误加 "files": ["public/dist/app.js"]，结果每次 composer install 都试图 require 一个未生成的 JS 文件，报错 Warning: require(...): failed to open stream。
多环境共用同一套 PHP 后端时，require-dev 会污染生产环境吗？
不会，但前提是部署时用 composer install --no-dev。
-
require-dev里的包（如phpunit/phpunit、laravel/pint）只在本地开发和 CI 中需要； - 生产环境运行
composer install默认会跳过require-dev，但如果你用了composer update或没加--no-dev，这些包就会被装进vendor/，增加攻击面和部署体积； - 更稳妥的做法是在 CI/CD 脚本中显式写死：
composer install --no-interaction --optimize-autoloader --no-dev
注意：即使没装 require-dev，只要 composer.lock 文件存在，install 就能还原完全一致的依赖树 —— 所以 composer.lock 必须提交到 Git，不能忽略。
为什么本地能跑通，上线后提示 Class not found？
90% 是因为 PSR-4 自动加载路径没对齐，尤其在 SPA 后台常混用两种结构：
- API 控制器放在
app/Http/Controllers/Api/，但composer.jsonautoload 写的是："App\": "app/"
→ 正确； - 如果误写成：
"App\": "app/Http/Controllers/"
→ 自动加载器会尝试加载AppApiUserController对应的文件路径为app/Http/Controllers/Api/UserController.php，但命名空间其实是AppHttpControllersApi，不匹配就报错； - 另一个常见原因是：PHP 运行用户（如
www-data）没权限读取vendor/composer/autoload_psr4.php，检查文件权限是否为644，目录为755。
调试方法：上线后手动执行 composer dump-autoload -o，再看错误是否消失 —— 如果消失了，说明旧的 autoload 文件缓存了错误映射。
