composer install 不能触发 npm install，因 Composer 完全不感知 package.json，npm install 失败时默认仍返回成功码 0；必须分步执行并显式校验退出码，且 lock 文件须各自独立生成与提交。
composer install 不能触发 npm install，这是根本前提
很多人误以为在 composer.json 的 scripts 里写 "post-install-cmd": ["npm install"] 就算“同步构建”，但实际只是 shell 命令调用，不是依赖协同。Composer 完全不感知 package.json 内容，也不校验 Node 环境是否存在——npm install 失败时，composer install 默认仍返回成功码 0，CI 流水线继续往下走，导致后续 PHP 迁移或缓存清理在缺失前端产物的环境下执行。
真正要让构建失败可感知，必须显式传递退出码：
"build-frontend": "cd frontend && npm ci --no-audit && npm run build || exit 1"
-
npm ci比npm install更可靠：强制按package-lock.json安装，不读本地缓存或全局模块 -
cd frontend必须存在且路径固定；否则加一层判断：@php -r "file_exists('frontend/package.json') && system('cd frontend && npm ci');" - Windows 下
&&不生效，建议统一用 Bash 脚本封装，或改用corepack统一管理 yarn/npm 版本
Node.js 和 PHP 锁文件必须各自独立生成并提交
composer.lock 和 package-lock.json（或 yarn.lock）是两种语言各自的“确定性快照”，它们之间没有映射关系，也不能互相替代。试图把 composer.lock 当作主干依赖源去驱动 Node 构建，会直接丢失 integrity 字段、resolved URL、二进制依赖（如 native addon）等关键元数据。
- CI 中必须分步执行：
composer install --no-dev --optimize-autoloader→npm ci --no-audit→npm run build，每步独立校验退出码 - 两个 lock 文件都必须提交到 Git：它们是重建环境的唯一依据，缺一不可
-
vendor/和node_modules/都必须进.gitignore；混放或互相引用会导致部署失败、CDN 路径错乱、权限问题
跨语言 SBOM 不能靠 composer 生成，得用各语言原生工具聚合
composer sbom:export 是不存在的命令，Composer 根本不支持 SPDX 或 CycloneDX 输出。它只解析 composer.json 和 composer.lock，对 package.json、pyproject.toml 完全无感知。强行用 Composer 工具链处理多语言 SBOM，结果一定是残缺的——比如漏掉 npm 包的 SRI 哈希、Python 包的 direct_url.json 记录。
- PHP 侧可用：
spdx-sbom-generator（基于composer.lock）或syndesis - Node.js 侧用：
npm sbom（npm ≥ 8.12）或cyclonedx-node-module - Python 侧推荐：
pipdeptree --freeze | cyclonedx-py，注意 pip ≥ 22.2 才能稳定输出哈希 - 最终 SBOM 必须由轻量脚本在统一构建上下文中聚合，而不是靠某一个工具“统一生成”
Docker 构建中 Node 和 PHP 环境必须解耦，不能共用镜像
在 Docker 中把 node 和 php 装在同一层镜像里，看似省事，实则掩盖了环境差异：Vite 要 Node ≥ 18，而某些 PHP 扩展（如 ext-grpc）在 Node 18 下编译失败；npm run build 卡住时日志只显示 Command failed with exit code 1，根本看不出是 Node 版本不匹配还是内存溢出。
- 正确做法是多阶段构建：用
node:18-slim单独构建前端，COPY --from=0 /app/frontend/dist /var/www/public/build到 PHP 镜像 - PHP 镜像里完全不装 Node，避免污染运行时环境和安全扫描误报
- CI 中应明确声明 Node 版本（如
.nvmrc或engines.node），并在脚本开头加版本校验：@php -r "$v = trim(shell_exec('node -v')); if (version_compare($v, '18.0.0', '<')) die('Node >= 18.0.0 required, got $v');
多语言微服务里最易被忽略的点是：锁文件时间戳、生成工具版本、网络代理策略都会影响哈希一致性。不同语言的构建必须在隔离环境中完成，再通过外部协调收口输出——不是谁管谁，而是谁都不该越界。
