Composer install 不会下载前端文件，因其仅管理 vendor/ 下的 PHP 包，对 node_modules、dist/ 等前端资源无感知；需借助 asset-packagist.org 和 composer-asset-plugin 实现自动拷贝，或通过 post-install-cmd 调用 npm 构建，但需注意环境兼容性与路径一致性。
composer install 为什么不会下载前端文件
Composer 是 PHP 的依赖管理工具，它只管 vendor/ 目录下的 PHP 包，对 node_modules、dist/、public/js 这类前端资源天生无感。你执行 composer install 后发现 CSS/JS 没生成、目录空空如也——不是配置错了，是它本来就不干这活。
常见错误现象：composer require some/frontend-package 成功，但项目里找不到任何 JS 文件；或者包里明明有 build/ 目录，却没被复制到 Web 可访问路径。
- PHP 包的
composer.json中type字段为library或project，默认不触发资源导出 - 前端包若未声明
extra.asset-installer-paths，Composer 不知道该把哪些文件拷到哪去 - 有些包把构建脚本写在
scripts.post-install-cmd里，但你的环境没装 Node.js 或没启用脚本执行（COMPOSER_DISABLE_FUNCTIONS或--no-scripts）
用 asset-packagist.org + composer-asset-plugin 实现自动拷贝
这是目前最轻量、兼容 PHP 7.4–8.2 且不侵入构建流程的方式：把前端包当“资产”处理，靠插件在 install 时自动提取并复制指定文件。
使用场景：需要引入 jQuery、Bootstrap、AdminLTE 等传统前端库，且不想手动下载、解压、放 public 目录；或团队不统一用 npm，但又要保持 Composer 单点管理。
立即学习“前端免费学习笔记（深入）”；
- 先安装插件：
composer global require fxp/composer-asset-plugin --no-plugins（注意加--no-plugins避免循环加载） - 在项目根目录
composer.json中添加仓库源："repositories": [{"type": "composer", "url": "https://asset-packagist.org"}] - 声明要拷贝的路径，例如引入 Bootstrap：
"extra": {"asset-installer-paths": {"public/js/jquery": ["npm-asset/jquery"], "public/css/bootstrap": ["npm-asset/bootstrap"]}} - 运行
composer require npm-asset/bootstrap，插件会自动从 CDN 下载压缩包、解压，并按规则复制文件
post-install-cmd 脚本里调用 npm build 的坑
如果你的前端包带 package.json 和 build 脚本（比如 Vue 组件库），想让 composer install 自动触发构建，就得靠 scripts.post-install-cmd。但这块最容易出问题。
性能影响：每次 composer install 都会跑一遍 npm install && npm run build，CI 构建时间可能翻倍；本地开发时重复构建还容易污染 node_modules 权限。
- 确保
npm在系统 PATH 中，否则脚本静默失败（查composer install -v输出末尾有没有sh: npm: not found） - 不要在脚本里用相对路径如
./node_modules/.bin/vue-cli-service，改用npx vue-cli-service build更健壮 - 避免在
post-install-cmd里做耗时操作，可加判断：if [ ! -f public/js/app.js ]; then npm run build; fi - 某些共享主机禁用
exec()，脚本直接跳过——此时得退回到手动构建 + git commit 静态文件
静态资源路径硬编码导致部署失败
很多教程教你在 config/app.php 或 Blade 模板里写死 public/vendor/some-lib/dist/some.css，上线后发现 404。这不是路径写错了，是资源实际位置和预期不一致。
原因常出在两处：一是插件提取时用了符号链接（symlink），而生产环境 Web 服务器没开 FollowSymLinks；二是包版本升级后，内部目录结构变了（比如 Bootstrap 5 把 css/ 改成 dist/css/），但你的 HTML 还在引用旧路径。
- 永远用 Laravel 的
@vite或原生asset()辅助函数，而不是直接写<link href="/css/app.css"> - 检查插件生成的实际路径：
ls -la public/js，确认文件真实存在且权限为 644 - 如果用了 CDN 托管（如 jsDelivr），别在
composer.json里配asset-installer-paths，那套机制就失效了——得换方案
真正麻烦的从来不是怎么拷文件，而是谁来保证路径在 dev/staging/prod 三个环境里始终对得上。手动维护容易漏，自动化又怕太重。选方案前先想清楚：你到底需要的是“一键同步”，还是“可控交付”。
