composer本身不管理前端依赖，仅通过scripts字段（如post-install-cmd）调用npm/yarn命令实现联动；必须提交composer.lock和package-lock.json，忽略vendor/与node_modules/，构建产物也应纳入.gitignore。
Composer 本身不安装 Node.js，也不能替代 npm 或 yarn。所谓“联动”，只是通过脚本触发命令，不是能力合并——搞反这点，后续所有配置都会出问题。
composer.json 的 scripts 是唯一可靠联动点
Composer 没有“前端依赖管理”功能，composer require vue 必然失败，Packagist 上不存在这类包。真正能打通的只有 scripts 字段，它允许你在 composer install 后自动执行 shell 命令。
- 推荐用
post-install-cmd和post-update-cmd，避免在pre-*阶段调用 Node 命令（此时package.json可能还没就位） - 加一层存在性判断，防止项目没前端时执行失败：
@php -r "file_exists('package.json') && system('npm ci --no-audit');" - 不要写
cd frontend && npm install这类路径硬编码，除非你 100% 确保目录结构固定；更稳妥的是把package.json放根目录，或用npm --prefix frontend ci -
npm ci比npm install更适合 CI/CD，它强制按package-lock.json安装，不会因本地缓存或全局模块干扰结果
Node.js 版本不匹配会导致构建静默失败
Composer 不检查、不约束、不切换 Node.js 版本。但 Vite/Webpack 等工具对 Node 版本敏感，比如 Vite v5 要求 Node ≥ 18.0.0，而你在 PHP 服务器上跑着 Node 16，npm run build 可能卡在语法报错或直接退出，日志里却只显示 “Command failed with exit code 1”。
- 项目根目录放
.nvmrc，内容写18.19.0（与 CI 配置一致），开发者运行nvm use即可切换 - 在
scripts里加校验步骤：@php -r "$v = trim(shell_exec('node -v')); if (version_compare($v, '18.0.0', '= 18.0.0 required, got $v'); }" - Docker 环境中别依赖宿主机 Node，用
node:18-slim镜像单独构建前端，再 COPY 到 PHP 镜像里——这才是解耦，不是“联动”
vendor/ 和 node_modules/ 必须同时进 .gitignore
很多人只忽略 vendor/，却把 node_modules/ 提交了，导致仓库体积暴涨、CI 下载慢、不同系统下 node_modules 权限/符号链接不一致。更隐蔽的问题是：某些 Composer 插件（如 old fxp/composer-asset-plugin）会偷偷往 vendor/ 里塞 JS 文件，和 node_modules/ 冲突。
-
.gitignore里这两行必须都有：/vendor/和/node_modules/ -
composer.lock和package-lock.json（或yarn.lock）必须提交——它们是依赖可重现的唯一依据 - 构建产物（如
public/build/或frontend/dist/）也应进.gitignore，除非你明确要 CDN 直接读取 Git 仓库（极少见）
最容易被忽略的其实是锁文件和构建路径的约定：团队没统一 npm run build 输出到哪，有人写 dist/，有人写 public/js/，PHP 就找不到资源；没人坚持提交 package-lock.json，CI 上装出来的依赖版本就可能和本地不一致——这些细节比“怎么联动”重要得多。
