macOS 下 Node.js 项目依赖项的本地安装与管理

核心原则是所有项目级依赖必须本地安装于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 后它会自动更新，确保可重现性。

常见依赖管理操作

• 升级单个依赖：运行 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 下的可执行文件。