Composer不能管理Node.js依赖，只负责PHP部分；混合项目需隔离职责、显式调度，禁用scripts中直接执行npm install，应通过上层工具（如Makefile、CI流程）分步控制，确保环境校验与错误透出。
Composer 不能管理 Node.js 依赖，也不该尝试让它管理——它只负责 PHP 部分；混合项目协作的关键是“隔离职责 + 显式调度”，不是“集成”。
composer.json 的 scripts 不该直接执行 npm install
常见错误是把 "post-install-cmd": ["npm install"] 塞进 composer.json，结果在 CI 或无 Node 环境的服务器上静默失败，甚至成功却没输出，导致前端构建产物缺失。
- Composer 默认不检查
node或npm是否可用，也不会报错提示环境缺失 -
npm install在根目录运行时，可能误装到项目顶层，而非真正的前端子目录（如resources/js/或frontend/） - 多个命令用数组写法（如
["cd frontend && npm ci", "cd frontend && npm run build"]）会并行启动，不保证顺序，且前一个失败不会中断后一个
必须用 && 链式调用并显式检查退出码
如果非要在 Composer 脚本里触发前端构建，必须用 shell 链式语法确保原子性，并让失败立即暴露。
- 正确写法示例：
"build-frontend": "cd resources/js && npm ci --no-audit && npm run build || exit 1" -
|| exit 1是关键：只要任意一步失败（如cd目录不存在、npm命令未找到、构建报错），整个脚本退出码为 1，composer install就会中止，避免后续 PHP 迁移或缓存清理在不完整环境下执行 - 不要用
system()或exec()在 PHP 代码里调用 npm —— 构建逻辑应完全收敛在package.json#scripts中
vendor/ 和 node_modules/ 绝对不能混放或互相引用
把 node_modules/ 放进 vendor/，或反过来让 Web 服务器直接访问 vendor/ 下的 JS 文件，既是安全漏洞，也破坏构建语义。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
立即学习“PHP免费学习笔记（深入）”；
-
vendor/是 PHP 运行时依赖，由autoload.php控制加载；node_modules/是构建时依赖，仅用于产出public/build/app.js这类静态资源 - PHP 模板里硬编码
<script src="../node_modules/some-lib/dist/some.js">会导致部署失败、CDN 路径错乱、版本更新后 404 - 推荐做法：用
composer.json的extra字段声明构建目标路径，例如："extra": {"frontend-dist": "public/build"}，再由前端构建脚本读取该值决定输出位置
跨语言依赖安装必须由上层工具统一调度
靠 composer install 单点触发全栈准备，看似方便，实则掩盖环境差异、弱化错误反馈、增加调试成本。
- CI/CD 流程应明确分步：
composer install --no-dev→npm ci --no-audit→npm run build，每步独立校验、日志可追溯 - 本地开发可用
Makefile或package.json#scripts封装，例如："scripts": {"setup": "composer install && cd resources/js && npm ci && npm run build"} - Node.js 版本需靠
.nvmrc+nvm use约束，Python 版本靠.python-version+pyenv local，这些和 Composer 无关，但必须写进 CONTRIBUTING.md
最容易被忽略的一点：构建产物（如 public/build/）不是源码，它不该出现在开发者的 Git 工作区里反复修改；而 package-lock.json 和 composer.lock 才是真正需要提交的“确定性契约”。
