npm 完整生命周期脚本及特点

生命周期脚本	触发时机	执行次数	主要用途	示例	特点与注意事项
`preinstall`	`npm install` 执行前	每次安装	环境检查、前置依赖安装	`"preinstall": "check-node-version"`	1. 在依赖下载前执行 2. 适合系统检查 3. 不要安装项目依赖
`install`	依赖安装过程中	自动	(很少手动定义)	-	npm 内部使用，一般不需要定义
`postinstall`	依赖安装完成后	每次安装	编译原生模块、生成配置文件	`"postinstall": "node-gyp rebuild"`	1. 用户安装后运行 2. 适合二进制编译 3. 用户可见
`prepare`	1. `npm install` 后 2. `npm publish` 前 3. `npm pack` 前	多次	构建任务、Git 钩子安装	`"prepare": "husky install"`	⭐ 最常用 1. 保证发布前构建 2. 本地开发也执行 3. 推荐用于构建
`prepublish`	`npm publish` 前（已废弃）	发布时	向后兼容	`"prepublish": "echo 'deprecated'"`	❌ npm@4 后废弃被 `prepare` 替代
`prepublishOnly`	仅 `npm publish` 前	发布时	发布前的专用检查	`"prepublishOnly": "npm test"`	1. 仅发布时运行 2. 适合运行测试 3. 不干扰开发
`prepack`	`npm pack` 或 `npm publish` 前（打包前）	打包时	准备打包文件	`"prepack": "clean-dist-folder"`	1. 在创建 tarball 前 2. 可修改打包内容
`postpack`	创建 tarball 后	打包时	清理临时文件	`"postpack": "rm -rf ./temp"`	打包后的清理工作
`preprepare`	`prepare` 之前	依赖 `prepare`	极少使用	-	几乎不需要
`postprepare`	`prepare` 之后	依赖 `prepare`	极少使用	-	几乎不需要
`prestart`	`npm start` 前	每次启动	启动前准备	`"prestart": "npm run build"`	启动应用前的准备
`poststart`	`npm start` 后	每次启动	启动后处理	`"poststart": "echo 'App started'"`	启动后的通知等
`prerestart`	`npm restart` 前	重启时	重启前操作	-	很少使用
`restart`	`npm restart`	重启时	自定义重启逻辑	-	覆盖默认重启行为
`postrestart`	`npm restart` 后	重启时	重启后操作	-	很少使用

执行顺序流程图

常用场景对比

🛠️ 开发环境设置

选择	理由
`prepare` (推荐)	保证开发者和 CI 环境一致性
`postinstall`	如果只需要用户安装后运行

📦 包发布流程

脚本	用途
`prepublishOnly`	运行测试，确保发布质量
`prepare`	构建生产代码
`prepack`	最终调整打包内容

🔧 原生模块编译

选择	理由
`postinstall`	用户安装后需要编译（如 node-gyp）

实用示例配置

json

复制代码

{
  "scripts": {
    // 开发相关
    "preinstall": "npx only-allow pnpm",
    "postinstall": "npm run build:addons",
    "prepare": "husky install && npm run build",
    
    // 构建相关
    "build": "tsc",
    "build:addons": "node-gyp rebuild",
    
    // 测试相关
    "test": "jest",
    "prepublishOnly": "npm run test && npm run build",
    
    // 启动相关
    "prestart": "npm run build",
    "start": "node dist/index.js",
    
    // 打包相关
    "prepack": "npm run clean-dist",
    "pack": "npm pack"
  }
}

重要注意事项

prepare vs postinstall：
- 对于包开发者 ：用 prepare（保证发布前构建）
- 对于包使用者 ：postinstall 会在安装后运行
- 对于构建工具 ：用 prepare（如 Husky、TypeScript 编译）

避免的陷阱：

❌ 不要在 preinstall 中安装项目依赖
❌ 避免 prepare 中有副作用（应幂等）
✅ prepublishOnly 只用于发布相关任务

环境变量：

bash

复制代码

# 判断是否在生产环境
if [ "$NODE_ENV" = "production" ]; then
  # 生产环境逻辑
fi

# 判断是否是 CI 环境
if [ "$CI" = "true" ]; then
  # CI 环境逻辑
fi

性能考虑：

生命周期脚本应尽量快速
避免阻塞操作
考虑添加进度提示