核心原则是所有项目级依赖必须本地安装于node_modules，由npm自动维护。需提交package-lock.json以确保版本精确一致；依赖分dependencies（运行时）和devdependencies（开发时），通过npm install或npm install --save-dev安装，禁止全局安装项目依赖。
在 macos 上管理 node.js 项目的本地依赖项，核心原则是：所有项目级依赖都应安装在项目目录内的 node_modules 文件夹中，由 npm 或 yarn（推荐 npm）自动维护，不依赖全局安装。这保证了项目可复现、环境隔离、协作一致。
本地依赖安装的基本流程
进入你的项目根目录（含 package.json），执行：
-
首次初始化项目：运行
npm init -y自动生成默认package.json -
安装生产依赖（如 Express、React）：运行
npm install express，会自动写入dependencies字段 -
安装开发依赖（如 ESLint、Vite）：运行
npm install eslint --save-dev或简写为npm install eslint -D，写入devDependencies -
一次性安装全部依赖：项目已有
package.json时，直接运行npm install（无参数），npm 会读取文件并安装所有列出的依赖到node_modules
理解 node_modules 与 package-lock.json
node_modules 是实际存放所有依赖包代码的文件夹，由 npm 自动创建和更新；而 package-lock.json 是关键的“锁定文件”，它精确记录了每个依赖包的版本号、下载地址、完整性哈希（integrity）及嵌套依赖树。这个文件必须提交到 Git，否则不同机器安装可能得到不一致的依赖结构，引发“在我机器上能跑”的问题。
不要手动修改 package-lock.json，也不要在项目中删除它。执行 npm install 后它会自动更新，确保可重现性。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
常见依赖管理操作
-
升级单个依赖：运行
npm update express（升级到符合package.json版本范围的最新兼容版），或npm install express@latest（强制升级到最新主版本） -
卸载依赖：运行
npm uninstall lodash（同时从package.json中移除），加-D可卸载开发依赖 -
检查依赖树：运行
npm list --depth=0查看已安装的一级依赖；用npm list express查看某包的安装路径和版本 -
清理无效依赖：运行
npm prune可删除package.json中未声明但存在于node_modules的包（例如手动复制进来的）
避免全局安装项目依赖
除非是 CLI 工具（如 create-react-app、typescript 编译器本身），否则不要用 npm install -g 安装项目运行所需的包。全局安装的包无法被 require() 或 import 引入，且版本不绑定项目，极易导致协作混乱。所有 require('express') 类依赖，必须是本地安装。
如果遇到 “command not found” 错误（比如运行 vite 报错），请确认该命令是否已在 package.json 的 scripts 中定义（如 "dev": "vite"），然后用 npm run dev 调用——npm 会自动优先使用本地 node_modules/.bin 下的可执行文件。
