NPM Script 实战：常用命令设计与封装｜Vue 工程化篇聚焦 Vue 项目 preview/release 命令

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

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

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

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

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

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

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

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

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

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

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

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

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

开篇

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

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

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

1.1 本质

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

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

{
  "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 项目：

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

Vue CLI 项目：

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

自定义端口：

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

3.3 容易踩的坑

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

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

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

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


"dev": "vite --mode development"

四、`build`：生产构建

4.1 作用

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

4.2 常见写法

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

构建前清理 dist：

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

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

带环境变量：

{
  "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 常见写法

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

Vite + ESLint：

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

Prettier 一起用：

{
  "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 常见写法


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

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

自定义端口：


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

6.3 容易踩的坑

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

七、`release`：发布流程

7.1 作用

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

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

7.2 常见写法

只做构建 + 版本号：

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

用 standard-version 自动生成 CHANGELOG：

{
  "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 配置：

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

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

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

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

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

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

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

开篇