npm scripts 与工具链

scripts 的价值不只是“把命令写短一点”，而是把团队真正需要反复执行的动作收敛成统一入口。这样本地开发、CI 和新成员上手都会更稳。

推荐设计原则

• 常用动作用清晰短名，如 dev、build、test
• 不要把特别复杂的逻辑硬塞进一行 shell
• 本地和 CI 尽量复用同一组脚本名
• 项目只保留一套主要包管理器入口

package.json scripts

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "preview": "nuxt preview",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "typecheck": "nuxi typecheck",
    "test": "vitest",
    "test:run": "vitest run",
    "prepare": "husky"
  }
}

生命周期钩子

{
  "scripts": {
    "prebuild": "rm -rf dist",
    "build": "tsc",
    "postbuild": "echo 'Build complete'",
    "preinstall": "npx only-allow pnpm",
    "postinstall": "nuxt prepare"
  }
}

pre 和 post 前缀会在对应脚本前后自动执行。

传递参数

npm run test -- --watch
pnpm test --watch          # pnpm 不需要 --

代码质量工具

ESLint

pnpm add -D eslint @antfu/eslint-config

eslint.config.mjs：

import antfu from "@antfu/eslint-config";

export default antfu({
  vue: true,
  typescript: true,
});

Prettier

pnpm add -D prettier

.prettierrc：

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100
}

lint-staged + Husky

提交前自动检查：

pnpm add -D husky lint-staged
pnpm exec husky init

package.json：

{
  "lint-staged": {
    "*.{ts,vue}": ["eslint --fix"],
    "*.{json,md,css}": ["prettier --write"]
  }
}

.husky/pre-commit：

pnpm exec lint-staged

构建工具

tsup 示例

pnpm add -D tsup

tsup.config.ts：

import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["cjs", "esm"],
  dts: true,
  clean: true,
});

版本管理与发包

Changesets

pnpm add -D @changesets/cli
pnpm changeset init

# 添加变更记录
pnpm changeset

# 更新版本号
pnpm changeset version

# 发布
pnpm changeset publish

手动发包

# 更新版本
npm version patch    # 0.0.1 -> 0.0.2
npm version minor    # 0.0.2 -> 0.1.0
npm version major    # 0.1.0 -> 1.0.0

# 发布
npm publish
npm publish --access public  # Scoped 包

实用 npx/dlx 命令

# 创建项目
pnpm dlx create-vite
pnpm dlx nuxi init my-app
pnpm dlx create-next-app

# 一次性工具
pnpm dlx taze          # 检查依赖更新
pnpm dlx depcheck      # 检查未使用依赖
pnpm dlx npm-check-updates -u  # 更新 package.json
pnpm dlx serve dist    # 快速启动静态服务器

参考链接

推荐的最小脚本集

• dev
• build
• preview 或 start
• test
• lint
• typecheck

这套最小集合已经能覆盖大多数现代前端或 Node 项目的日常工作流。

常见问题

为什么脚本在我电脑能跑，在 CI 不行

通常是环境变量、路径、Shell 差异或依赖安装方式不一致。优先让 CI 也调用同名 scripts，而不是写两套命令。

脚本越来越长怎么办

当一条脚本开始塞很多条件、循环和平台分支时，通常就该把它拆到独立脚本文件里。

npm、pnpm、bun 的脚本要不要混着写

不建议。项目里最好明确主入口，避免不同成员执行出不同依赖树和行为。

• npm scripts 文档 — 官方文档
• ESLint — 官网
• Prettier — 官网
• Husky — Git Hooks
• Changesets — 版本管理
• Node.js 生态工具链 — 如果你还没统一版本管理器和包管理器