Node.js依赖管理与npm install/run命令实践

脚本专家

Node.js项目的依赖与脚本入口
Node.js项目把外部模块记录在package.json，把实际安装结果放进node_modules，并用package-lock.json锁定版本。依赖通常来自npm registry，也可以来自GitHub或本地文件；版本由semver描述，例如^1.2.3表示允许小版本更新。依赖管理要同时服务开发、测试、构建和生产运行，锁文件用于保证不同环境中的版本一致。

五类依赖字段及使用场景
1. dependencies：生产运行所需依赖，如express、axios。
2. devDependencies：只在开发、测试、构建阶段使用，如typescript、jest、tsx。
3. optionalDependencies：可运行但非必须的依赖，安装失败不影响项目，例如特定平台加速库esbuild原生模块。
4. peerDependencies：声明与宿主项目的兼容依赖，如React插件对react版本的要求。
5. bundledDependencies：发布包时强制打包的依赖，使用较少，记录为数组。
分类正确与否会影响生产包体积、部署速度和团队复现环境。例如express进入dependencies，tsx进入devDependencies：

2. "dependencies": { "express": "^4.18.2" },
3. "devDependencies": { "tsx": "^4.7.0" }

复制代码

npm install 命令族：按目标选择参数
基础命令 npm install 或 npm i 会安装package.json中的dependencies和devDependencies，把包下载到node_modules，并生成或更新package-lock.json；如果node_modules已存在，可能只更新不一致的依赖。克隆项目后首次初始化和部署前安装依赖都可使用。
安装指定包为生产依赖：npm install express。它会把express写入dependencies，并下载到node_modules。
安装开发工具：npm install -D tsx 或 npm install --dev tsx，将包写入devDependencies，适用于eslint、tsx等只在开发和构建阶段使用的工具。
全局安装：npm install -g create-react-app。包进入系统全局目录，不记录到项目package.json，可在任意路径通过命令行调用，适合CLI工具。
生产环境安装：npm install --production，只安装dependencies，忽略devDependencies，以减少磁盘占用和部署开销。
一致性安装：npm ci，会清除现有node_modules，再按package-lock.json安装精确版本；比npm install更快，适合CI/CD和团队协作复现。
其他常用形式包括安装指定版本 npm install express@4.17.1、安装可选依赖 npm install --save-optional <package>、安装同伴依赖 npm install --save-peer <package>，以及安装本地包 npm install ./path/to/local-package。命令示例如下：

2. npm install
3. npm i
4. npm install express
5. npm install -D tsx
6. npm install -g create-react-app
7. npm install --production
8. npm ci
9. npm install express@4.17.1
10. npm install --save-optional <package>
11. npm install --save-peer <package>
12. npm install ./path/to/local-package

复制代码

npm run 如何执行package.json脚本
scripts字段把开发、构建、启动和测试命令固定下来。npm run <script-name>会调用对应命令；start、test等特殊脚本可以省略run，直接执行npm start或npm test。运行npm run时，npm会把node_modules/.bin加入PATH，因此本地安装的tsx、jest等CLI可直接调用，不要求全局安装。
例如项目可定义这组脚本：

2. "scripts": {
3.   "dev": "tsx src/index.ts",
4.   "build": "tsc",
5.   "start": "node dist/index.js",
6.   "test": "jest"
7. }

复制代码

对应操作是：npm run dev执行tsx src/index.ts启动TypeScript开发环境；npm run build执行tsc编译TypeScript；npm start执行node dist/index.js启动生产服务器；npm test运行jest。执行npm run会列出scripts中的可用脚本，适合调试前确认入口。
生命周期钩子方面，npm支持pre<script>和post<script>。例如定义"predev": "echo Starting dev..."后，运行npm run dev前会先执行predev。向脚本传参要加--：npm run dev -- --port=3000会把--port=3000传给脚本。

2. npm run dev
3. npm run build
4. npm start
5. npm test
6. npm run dev -- --port=3000
7. npm run

复制代码

全局安装与项目本地安装的取舍
非全局安装是默认方式，依赖位于项目node_modules，记录在dependencies或devDependencies，版本与项目绑定，便于版本控制和团队协作，但每个项目都要单独安装，占用空间更多。全局安装位于系统全局目录，不写入package.json，安装一次可跨项目使用，缺点是版本可能与项目要求不一致，也不容易纳入版本控制。CLI工具可全局安装；一次性工具优先用npx <package>动态运行，避免全局版本冲突。

开发与部署时的落地检查
开发者侧要按用途选择依赖：核心功能放dependencies，开发工具放devDependencies，非必须优化包放optionalDependencies；尽量减少全局安装，脚本名保持清晰并考虑跨平台兼容，定期用npm outdated检查过时依赖，用npm update按semver更新。package-lock.json应提交到版本控制，不要手动修改node_modules。
使用者侧部署时先用npm ci保证锁文件一致，生产环境配合npm install --production减少安装内容；运行前检查scripts字段，按需执行npm run dev、npm run build、npm run start。需要验证Node.js和npm版本时使用node -v、npm -v，并确认锁文件存在。
常见问题排查：依赖安装失败先检查网络、缓存和包名拼写，可清理缓存npm cache clean --force；脚本执行失败先检查scripts定义和依赖是否安装。性能方面，生产安装用--production减少开销，CI场景用npm ci按锁文件复现并减少安装偏差。

总结来说，package.json负责声明依赖与脚本，package-lock.json负责锁定安装结果，node_modules保存实际包。掌握install的参数差异、run的PATH与钩子机制，以及全局和本地安装的边界，才能让Node.js项目在开发、构建、测试和部署阶段保持一致。