NPM Script 实战：常用命令设计与封装｜Vue 工程化篇

【NPM Script】Vue 前端工程化实操：从核心封装逻辑到落地，彻底搞懂 npm run 常用命令最佳写法，避开端口占用、环境变量、多环境构建高频坑！

📑 文章目录

开篇
[一、NPM Script 是什么？为什么用它？](#一、NPM Script 是什么？为什么用它？)
- [1.1 本质](#1.1 本质)
- [1.2 为什么要用 NPM Script？](#1.2 为什么要用 NPM Script？)
二、常用命令的设计思路
三、dev：开发环境启动
- [3.1 作用](#3.1 作用)
- [3.2 常见写法](#3.2 常见写法)
- [3.3 容易踩的坑](#3.3 容易踩的坑)
四、build：生产构建
- [4.1 作用](#4.1 作用)
- [4.2 常见写法](#4.2 常见写法)
- [4.3 容易踩的坑](#4.3 容易踩的坑)
五、lint：代码规范检查
- [5.1 作用](#5.1 作用)
- [5.2 常见写法](#5.2 常见写法)
- [5.3 容易踩的坑](#5.3 容易踩的坑)
六、preview：预览生产构建
- [6.1 作用](#6.1 作用)
- [6.2 常见写法](#6.2 常见写法)
- [6.3 容易踩的坑](#6.3 容易踩的坑)
七、release：发布流程
- [7.1 作用](#7.1 作用)
- [7.2 常见写法](#7.2 常见写法)
- [7.3 容易踩的坑](#7.3 容易踩的坑)
[八、完整示例：一套推荐 scripts](#八、完整示例：一套推荐 scripts)
九、设计规范小结
- [9.1 命名习惯](#9.1 命名习惯)
- [9.2 顺序建议](#9.2 顺序建议)
- [9.3 跨平台](#9.3 跨平台)
十、小结
[🔍 本系列专栏导航](#🔍 本系列专栏导航)

同学们好，我是 Eugene（尤金），一个拥有多年中后台开发经验的前端工程师~

（Eugene 发音很简单，/juːˈdʒiːn/，大家怎么顺口怎么叫就好）

你是否也有过：明明学过很多技术，一到关键时候却讲不出来、甚至写不出来？

你是否也曾怀疑自己，是不是太笨了，明明感觉会，却总差一口气？

就算想沉下心从头梳理，可工作那么忙，回家还要陪伴家人。

一天只有24小时，时间永远不够用，常常感到力不从心。

技术行业，本就是逆水行舟，不进则退。

如果你也有同样的困扰，别慌。

从现在开始，跟着我一起心态归零 ，利用碎片时间，来一次彻彻底底的基础扫盲。

这一次，我们一起慢慢来，扎扎实实变强。

不搞花里胡哨的理论堆砌，只分享看得懂、用得上的前端干货，

咱们一起稳步积累，真正摆脱「面向搜索引擎写代码」的尴尬。

开篇

如果你用过 npm run dev、npm run build，但不太清楚它们是怎么来的、为什么要这么写、踩坑会踩在哪，这篇文章就是写给你的。

我们会从「命令怎么设计」和「怎么封装」两个维度来讲，面向会写 JS 但概念有点混、或想系统补基础的同学，不讲玄学原理，只讲日常该怎么做。

一、NPM Script 是什么？为什么用它？

1.1 本质

npm run xxx 执行的是 package.json 里 scripts 字段里对应的命令。

本质就是：把常用的、难记的命令，封装成简短好记的别名。

json 复制代码

{
  "name": "my-app",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

npm run dev → 执行 vite
npm run build → 执行 vite build

1.2 为什么要用 NPM Script？

统一入口：团队所有人用同一套命令，不需要记复杂命令行参数
跨平台 ：在不同系统下统一用 npm run xxx，不依赖不同 shell 语法
可组合：可以把多条命令串在一起（如 lint + build）
生态习惯 ：各种脚手架、教程默认都基于 package.json scripts

二、常用命令的设计思路

开发流程里常见的阶段：开发、构建、检查、预览、发布。对应到 scripts，常见命名是：

阶段	典型命令	作用
开发	`dev`	启动开发服务器，热更新
构建	`build`	打包生产代码
检查	`lint`	代码规范检查
预览	`preview`	本地预览生产构建结果
发布	`release`	发布到仓库 / 上线

接下来按这几个命令逐一说明怎么设计、怎么封装。

三、`dev`：开发环境启动

3.1 作用

启动开发服务器
支持热更新（保存即刷新）
通常带 source map，方便调试

3.2 常见写法

Vite 项目：

json 复制代码

{
  "scripts": {
    "dev": "vite"
  }
}

Vue CLI 项目：

json 复制代码

{
  "scripts": {
    "dev": "vue-cli-service serve"
  }
}

自定义端口：

json 复制代码

{
  "scripts": {
    "dev": "vite --port 3000"
  }
}

3.3 容易踩的坑

端口被占用如果 5173 被占，Vite 会尝试下一个端口。要固定端口，可以写：

json 复制代码

"dev": "vite --port 3000 --strictPort"

--strictPort 表示端口被占直接报错，而不是自动换端口。

环境变量 需要区分开发/生产时，可用 .env.development 或 .env.local，或在命令里加：

json 复制代码

"dev": "vite --mode development"

四、`build`：生产构建

4.1 作用

把源码打包成生产可用文件
压缩、混淆、tree-shaking
输出到 dist（或自定义目录）

4.2 常见写法

json 复制代码

{
  "scripts": {
    "build": "vite build"
  }
}

构建前清理 dist：

json 复制代码

{
  "scripts": {
    "build": "rimraf dist && vite build"
  }
}

rimraf 是跨平台的 rm -rf，需要安装：npm i -D rimraf

带环境变量：

json 复制代码

{
  "scripts": {
    "build": "vite build --mode production",
    "build:staging": "vite build --mode staging"
  }
}

4.3 容易踩的坑

dist 没清空 旧文件可能残留，建议用 rimraf dist && 先删再构建。
环境变量没生效 构建时用 .env.production，且变量必须以 VITE_ 开头（Vite 约定）。
多环境构建 可拆成多个命令：build、build:staging、build:test 等。

五、`lint`：代码规范检查

5.1 作用

检查语法、风格、潜在问题
支持自动修复（如 ESLint 的 --fix）

5.2 常见写法

json 复制代码

{
  "scripts": {
    "lint": "eslint . --ext .vue,.js,.ts",
    "lint:fix": "eslint . --ext .vue,.js,.ts --fix"
  }
}

Vite + ESLint：

json 复制代码

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

Prettier 一起用：

json 复制代码

{
  "scripts": {
    "lint": "eslint . && prettier --check .",
    "lint:fix": "eslint . --fix && prettier --write ."
  }
}

5.3 容易踩的坑

遗漏文件 确保 .eslintignore 里排除 node_modules、dist 等，否则会很慢。
和 Prettier 冲突 建议 ESLint 只做逻辑检查，Prettier 做格式，可配合 eslint-config-prettier 关掉 ESLint 的格式规则。
提交前检查 可用 husky + lint-staged 在 git commit 前自动跑 lint。

六、`preview`：预览生产构建

6.1 作用

在本地用生产构建结果跑一次
用来验证打包后的真实表现
和开发模式有差别（压缩、路由等）

6.2 常见写法

json 复制代码

{
  "scripts": {
    "build": "vite build",
    "preview": "vite preview"
  }
}

vite preview 会先读取 dist，所以需先执行 npm run build。

自定义端口：

json 复制代码

{
  "scripts": {
    "preview": "vite preview --port 4173"
  }
}

6.3 容易踩的坑

先 build 再 preview 忘记 build 直接 preview，会用到旧的 dist。
线上路由 404 SPA 需配置服务器 fallback 到 index.html，本地 preview 没问题不代表线上没问题。

七、`release`：发布流程

7.1 作用

发布不是单一命令，而是一套流程，通常包括：

跑测试
跑 lint
构建
更新版本号
打 tag
推送代码
发布到 npm 或 CI 部署

7.2 常见写法

只做构建 + 版本号：

json 复制代码

{
  "scripts": {
    "release": "npm run lint && npm run build && npm version patch"
  }
}

用 standard-version 自动生成 CHANGELOG：

json 复制代码

{
  "scripts": {
    "release": "npm run lint && npm run build && standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major"
  }
}

语义化版本说明：

patch：1.0.0 → 1.0.1（bug 修复）
minor：1.0.0 → 1.1.0（新功能，向后兼容）
major：1.0.0 → 2.0.0（破坏性变更）

7.3 容易踩的坑

没测就 release 建议把 test 写进 release 流程：npm run test && npm run lint && npm run build。
忘记提交 npm version 会改 package.json，需要再 git add 和 git commit。
npm 发布 发布到 npm 时要 npm publish，并注意 .npmignore，避免把源码、测试等都发出去。

八、完整示例：一套推荐 scripts

下面是一套可直接参考的 package.json scripts 配置：

json 复制代码

{
  "name": "my-vue-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite --port 3000",
    "build": "rimraf dist && vite build",
    "build:staging": "rimraf dist && vite build --mode staging",
    "preview": "vite preview --port 4173",
    "lint": "eslint . --ext .vue,.js,.ts",
    "lint:fix": "eslint . --ext .vue,.js,.ts --fix",
    "format": "prettier --write \"src/**/*.{vue,js,ts,css,json}\"",
    "type-check": "vue-tsc --noEmit",
    "test": "vitest",
    "test:run": "vitest run",
    "release": "npm run lint && npm run type-check && npm run test:run && npm run build && npm version patch",
    "release:minor": "npm run release -- --release-as=minor",
    "release:major": "npm run release -- --release-as=major"
  },
  "devDependencies": {
    "eslint": "^8.0.0",
    "prettier": "^3.0.0",
    "rimraf": "^5.0.0",
    "vite": "^5.0.0",
    "vitest": "^1.0.0",
    "vue-tsc": "^1.0.0"
  }
}

命令含义简要说明：

dev：开发，端口 3000
build：清空 dist 后构建
build:staging：staging 环境构建
preview：预览构建产物，端口 4173
lint / lint:fix：ESLint 检查 / 自动修复
format：Prettier 格式化
type-check：TypeScript 类型检查（若用 TS）
test / test:run：单元测试（watch / 单次）
release / release:minor / release:major：发布流程（lint + 类型检查 + 测试 + 构建 + 版本号）

九、设计规范小结

9.1 命名习惯

主命令：dev、build、lint、preview
带后缀：lint:fix、build:staging、test:run
保持简短、语义明确

9.2 顺序建议

依赖前置：rimraf dist && vite build
多条串行：lint && build

9.3 跨平台

删除目录用 rimraf 而不是 rm -rf
环境变量用 cross-env（如需要）

十、小结

命令	核心作用	注意点
`dev`	开发服务	端口、环境变量
`build`	生产构建	清空 dist、多环境
`lint`	规范检查	配合 Prettier、提交前检查
`preview`	本地预览构建	先 build 再 preview
`release`	发布流程	测试、版本号、提交

NPM Script 就是把「难记、易错」的命令封装成「好记、统一」的入口，设计时考虑：命名清晰、步骤可组合、能跨平台、团队习惯一致。按上面这套思路，日常项目足够用，也能在踩坑时有方向可排查。

🔍 本系列专栏导航

一、《Vite 实战教程：alias/env/proxy 配置 + 打包优化避坑｜Vue 工程化篇》
二、《Monorepo + pnpm workspace 落地实操：Vue 中后台多项目 / 组件库 / 公共包管理｜Vue 工程化篇》
三、《Vue/Vite 多环境配置实战：dev、test、prod 差异区分与避坑指南｜Vue 工程化篇》

四、《NPM Script 实战：常用命令设计与封装｜Vue 工程化篇》

👉 跟着系列慢慢学，把技术功底扎扎实实地打牢～

学习本就是一场持久战，不需要急着一口吃成胖子。哪怕今天你只记住了一点点，这都是实打实的进步。

后续我还会继续用这种大白话、讲实战的方式，带大家扫盲更多前端基础。

关注我，不迷路，咱们把那些曾经模糊的知识点，一个个彻底搞清楚。

如果你觉得这篇内容对你有帮助，不妨点赞+收藏，下次写代码卡壳时，拿出来翻一翻，比搜引擎更靠谱。

我是 Eugene，你的电子学友，我们下一篇干货见～

NPM Script 实战：常用命令设计与封装｜Vue 工程化篇

📑 文章目录

开篇

一、NPM Script 是什么？为什么用它？

1.1 本质

1.2 为什么要用 NPM Script？

二、常用命令的设计思路

三、dev：开发环境启动

3.1 作用

3.2 常见写法

3.3 容易踩的坑

四、build：生产构建

4.1 作用

4.2 常见写法

4.3 容易踩的坑

五、lint：代码规范检查

5.1 作用

5.2 常见写法

5.3 容易踩的坑

六、preview：预览生产构建

6.1 作用

6.2 常见写法

6.3 容易踩的坑

七、release：发布流程

7.1 作用

7.2 常见写法

7.3 容易踩的坑

八、完整示例：一套推荐 scripts

九、设计规范小结

9.1 命名习惯

9.2 顺序建议

9.3 跨平台

十、小结

🔍 本系列专栏导航

三、`dev`：开发环境启动

四、`build`：生产构建

五、`lint`：代码规范检查

六、`preview`：预览生产构建

七、`release`：发布流程