Vue/Vite 多环境配置实战：dev、test、prod 差异区分与避坑指南｜Vue 工程化篇

【Vue/Vite环境配置】+【前端中后台开发】：从环境变量区分到落地实操，彻底搞懂多环境配置的最佳写法，避开mock未关、接口地址错误高频坑！

📑 文章目录

一、为什么需要环境区分？
- [1.1 先说人话：三个环境分别干啥](#1.1 先说人话：三个环境分别干啥)
二、环境是怎么被识别的？
- [2.1 Vue CLI / Vite 里的 NODE_ENV 与 MODE](#2.1 Vue CLI / Vite 里的 NODE_ENV 与 MODE)
- [2.2 环境变量文件优先级（Vite 为例）](#2.2 环境变量文件优先级（Vite 为例）)
三、常见配置项与差异
四、环境文件与配置结构示例
- [4.1 目录与文件](#4.1 目录与文件)
- [4.2 环境文件内容](#4.2 环境文件内容)
五、统一的配置入口：src/config/env.js
[六、baseURL 在请求里的使用](#六、baseURL 在请求里的使用)
- [6.1 在 axios 中配置](#6.1 在 axios 中配置)
- [6.2 容易踩的坑](#6.2 容易踩的坑)
[七、Mock 开关管理](#七、Mock 开关管理)
- [7.1 思路](#7.1 思路)
- [7.2 简单实现](#7.2 简单实现)
- [7.3 生产环境一定要关 mock](#7.3 生产环境一定要关 mock)
八、日志级别
- [8.1 为什么需要日志级别](#8.1 为什么需要日志级别)
- [8.2 简易日志封装](#8.2 简易日志封装)
[九、package.json 脚本](#九、package.json 脚本)
十、自检清单（部署前建议过一遍）
十一、小结
[🔍 本系列专栏导航](#🔍 本系列专栏导航)

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

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

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

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

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

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

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

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

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

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

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

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

一、为什么需要环境区分？

1.1 先说人话：三个环境分别干啥

dev（开发）：本地开发，连本地或开发接口，有 mock、热更新、详细日志。
test（测试）：交给测试同学用的，联调接口，通常和 dev 类似，但更接近真实环境。
prod（生产）：真实线上，真实域名、真实接口，不能有 mock，日志要收敛，不能泄露敏感信息。

如果所有环境都用同一套配置，会有这些问题：

本地写死生产域名，直接联调生产，有安全风险，也不符合规范。
线上还开着 mock，导致接口没真正请求，功能异常。
生产环境打大量 console，影响性能，也暴露调试信息。

所以，环境区分的目的就是：在不同环境下，用不同的配置。

二、环境是怎么被识别的？

2.1 Vue CLI / Vite 里的 `NODE_ENV` 与 `MODE`

Vue 工程常见构建方式：Vue CLI 或 Vite。

Vue CLI：

默认有：development、production、test。
执行 npm run serve 时：NODE_ENV = 'development'。
执行 npm run build 时：NODE_ENV = 'production'。
如果脚本里写了 "test": "vue-cli-service build --mode test"，会加载 .env.test。

Vite：

使用 MODE，默认有 development、production。
npm run dev → MODE = 'development'。
npm run build → MODE = 'production'。
通过 --mode test 可加 test 模式，加载 .env.test。

注意：Vite 没有内置 test 模式，需要你自己加脚本和 .env.test。

2.2 环境变量文件优先级（Vite 为例）

Plain 复制代码

.env                # 所有环境都会加载
.env.local          # 所有环境加载，一般加到 .gitignore
.env.[mode]         # 只在指定 mode 下加载
.env.[mode].local   # 同上，但本地覆盖，不进 git

加载顺序（后加载的覆盖先加载的）：

Plain 复制代码

.env < .env.local < .env.[mode] < .env.[mode].local

三、常见配置项与差异

下面这些是日常开发里最常要区分的：

配置项	dev	test	prod
baseURL	开发/本地接口地址	测试环境接口地址	生产正式接口地址
mock	可开启	一般关闭	必须关闭
日志级别	全开（debug/info）	适中（info/warn）	仅 error 或关闭
各种开关	调试工具可开	按需	大多关闭

四、环境文件与配置结构示例

4.1 目录与文件

Plain 复制代码

project/
├── .env
├── .env.development
├── .env.test
├── .env.production
├── src/
│   └── config/
│       └── env.js

4.2 环境文件内容

.env（公共，所有环境都会用到）：

Plain 复制代码

# 公共说明
VITE_APP_TITLE=我的Vue项目

.env.development：

Plain 复制代码

# 开发环境
VITE_APP_BASE_URL=http://localhost:3000/api
VITE_APP_MOCK=true
VITE_APP_LOG_LEVEL=debug
VITE_APP_DEVTOOLS=true

.env.test：

Plain 复制代码

# 测试环境
VITE_APP_BASE_URL=https://test-api.example.com
VITE_APP_MOCK=false
VITE_APP_LOG_LEVEL=info
VITE_APP_DEVTOOLS=false

.env.production：

Plain 复制代码

# 生产环境
VITE_APP_BASE_URL=https://api.example.com
VITE_APP_MOCK=false
VITE_APP_LOG_LEVEL=error
VITE_APP_DEVTOOLS=false

说明：Vite 只会把以 VITE_ 开头的变量注入到客户端，其他变量只在构建时可用。Vue CLI 用的是 VUE_APP_ 前缀。

五、统一的配置入口：`src/config/env.js`

把「环境变量」和「业务语义」解耦，后面改环境变量前缀或结构时，只需改这一处。

js 复制代码

// src/config/env.js

/**
 * 环境配置统一入口
 * 目的：从 process.env 中读出变量，转化成业务使用的配置对象
 */
const config = {
  // 接口基础地址
  baseURL: import.meta.env.VITE_APP_BASE_URL || '',

  // 是否开启 mock（生产环境必须为 false）
  mock: import.meta.env.VITE_APP_MOCK === 'true',

  // 日志级别：'debug' | 'info' | 'warn' | 'error' | 'none'
  logLevel: import.meta.env.VITE_APP_LOG_LEVEL || 'info',

  // 是否开启调试工具（如 vConsole）
  devTools: import.meta.env.VITE_APP_DEVTOOLS === 'true',

  // 当前环境标识（方便在代码里做分支判断）
  isDev: import.meta.env.DEV,
  isProd: import.meta.env.PROD,
  mode: import.meta.env.MODE,
}

export default config

说明：

import.meta.env.DEV / PROD 是 Vite 内置，MODE 对应 --mode。
VITE_APP_MOCK 是字符串，所以用 === 'true' 判断。
Vue CLI 环境下，用 process.env.VUE_APP_xxx 和 process.env.NODE_ENV 等。

六、baseURL 在请求里的使用

6.1 在 axios 中配置

js 复制代码

// src/api/request.js
import axios from 'axios'
import config from '@/config/env'

const request = axios.create({
  baseURL: config.baseURL,
  timeout: 10000,
})

// 请求拦截器示例
request.interceptors.request.use(
  (cfg) => {
    // 可以在这里加 token 等
    return cfg
  },
  (err) => Promise.reject(err)
)

// 响应拦截器示例
request.interceptors.response.use(
  (res) => res.data,
  (err) => Promise.reject(err)
)

export default request

这样，不同环境的 baseURL 会自动切换。

6.2 容易踩的坑

baseURL 为空 检查 .env.[mode] 是否被正确加载，以及变量名是否带 VITE_ 前缀。
相对路径 vs 绝对路径 baseURL: '/api' 会走当前域名；写 http://xxx 是跨域，需要后端 CORS 或代理。
开发时跨域 开发环境用 Vite 的 proxy 代理，避免跨域；生产环境用 nginx 代理或后端 CORS。

js 复制代码

// vite.config.js 开发环境代理示例
export default {
  server: {
    proxy: {
      '/api': {
        target: 'https://test-api.example.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
}

这时 .env.development 里可以写 VITE_APP_BASE_URL=/api，通过代理转发到真实接口。

七、Mock 开关管理

7.1 思路

在 dev 开启 mock，test/prod 关闭。用 config.mock 控制是否走 mock 逻辑。

7.2 简单实现

js 复制代码

// src/api/request.js
import config from '@/config/env'

// 假设使用 axios-mock-adapter 或自己写的 mock
let mockAdapter = null

if (config.mock) {
  import('@/mock').then((module) => {
    mockAdapter = module.default
    // 将 mockAdapter 应用到 axios 实例
  })
}

// 或者：根据 config.mock 决定是否注册 mock 路由
if (config.mock) {
  // 只在开发环境加载 mock，生产打包时不会包含（配合动态 import）
  import('@/mock').then((m) => m.setup())
}

注意：

用 if (config.mock) 做守卫，避免在 prod 里注册 mock。
用动态 import()，生产构建时如果 mock 代码没被引用，可以被 tree-shake 掉，减小包体积。

7.3 生产环境一定要关 mock

如果生产环境 mock 没关，接口会走本地 mock，真实接口不会被调用，会导致功能异常。部署前务必检查 VITE_APP_MOCK 在生产环境为 false 或未设置。

八、日志级别

8.1 为什么需要日志级别

dev：需要详细日志排查问题。
prod：只保留错误日志，减少性能开销和敏感信息暴露。

8.2 简易日志封装

js 复制代码

// src/utils/logger.js
import config from '@/config/env'

const LOG_LEVELS = {
  debug: 0,
  info: 1,
  warn: 2,
  error: 3,
  none: 4,
}

const currentLevel = LOG_LEVELS[config.logLevel] ?? LOG_LEVELS.info

function shouldLog(level) {
  return LOG_LEVELS[level] >= currentLevel
}

const logger = {
  debug(...args) {
    if (shouldLog('debug')) console.log('[DEBUG]', ...args)
  },
  info(...args) {
    if (shouldLog('info')) console.info('[INFO]', ...args)
  },
  warn(...args) {
    if (shouldLog('warn')) console.warn('[WARN]', ...args)
  },
  error(...args) {
    if (shouldLog('error')) console.error('[ERROR]', ...args)
  },
}

export default logger

使用：

js 复制代码

import logger from '@/utils/logger'

logger.debug('调试信息', someData)  // dev 能看到，prod 通常看不到
logger.error('请求失败', err)       // 各环境都能看到

九、package.json 脚本

json 复制代码

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "build:test": "vite build --mode test",
    "build:prod": "vite build --mode production"
  }
}

npm run dev → 读 .env.development。
npm run build → 默认 production，读 .env.production。
npm run build:test → 读 .env.test。

十、自检清单（部署前建议过一遍）

检查项	说明
baseURL	prod 是否指向生产接口地址
mock	prod 必须关闭
日志级别	prod 建议 error 或 none
调试工具	prod 关闭 vConsole 等
敏感信息	不要写进 .env 并提交到 git
.env.local	是否在 .gitignore 中

十一、小结

三个环境各司其职：dev 开发、test 联调、prod 上线。
用环境变量文件区分配置 ：.env.development / .env.test / .env.production。
统一配置入口 ：config/env.js 封装环境变量，业务只依赖 config。
重点配置：baseURL、mock、日志级别、调试开关。
部署前检查：prod 的 mock 关闭、日志收敛、baseURL 正确。

🔍 本系列专栏导航

一、《Vite 实战教程：alias/env/proxy 配置 + 打包优化避坑｜Vue 工程化篇》
二、《Monorepo + pnpm workspace 落地实操：Vue 中后台多项目 / 组件库 / 公共包管理｜Vue 工程化篇》

三、《Vue/Vite 多环境配置实战：dev、test、prod 差异区分与避坑指南｜Vue 工程化篇》
四、《NPM Script 实战：常用命令设计与封装｜Vue 工程化篇》

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

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

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

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

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

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

Vue/Vite 多环境配置实战：dev、test、prod 差异区分与避坑指南｜Vue 工程化篇

📑 文章目录

一、为什么需要环境区分？

1.1 先说人话：三个环境分别干啥

二、环境是怎么被识别的？

2.1 Vue CLI / Vite 里的 NODE_ENV 与 MODE

2.2 环境变量文件优先级（Vite 为例）

三、常见配置项与差异

四、环境文件与配置结构示例

4.1 目录与文件

4.2 环境文件内容

五、统一的配置入口：src/config/env.js

六、baseURL 在请求里的使用

6.1 在 axios 中配置

6.2 容易踩的坑

七、Mock 开关管理

7.1 思路

7.2 简单实现

7.3 生产环境一定要关 mock

八、日志级别

8.1 为什么需要日志级别

8.2 简易日志封装

九、package.json 脚本

十、自检清单（部署前建议过一遍）

十一、小结

🔍 本系列专栏导航

2.1 Vue CLI / Vite 里的 `NODE_ENV` 与 `MODE`

五、统一的配置入口：`src/config/env.js`