前端多环境配置规范：dev/test/pre/prod 环境差异与配置，避免生产环境踩坑｜工程化与协作规范篇

【多环境配置 & Vue/Vite工程化】前端团队协作场景：从环境定义到落地配置，彻底搞懂dev/test/pre/prod区分规范，避开线上环境踩坑！

📑 文章目录

• 一、四个环境到底在干什么？
  • 1.1 dev（开发环境）
  • 1.2 test（测试环境）
  • 1.3 pre（预发 / 预生产环境）
  • 1.4 prod（生产环境）
• 二、为什么必须区分环境？
• 三、Vue 项目中如何配置多环境？
  • 3.1 方案一：Vue CLI（create-vue / @vue/cli）
  • 3.2 方案二：Vite 项目
• 四、统一封装：请求与接口切换
• 五、常见踩坑与规范
  • 5.1 接口地址写死
  • 5.2 环境变量未生效
  • 5.3 生产环境开启 Source Map
  • 5.4 在代码中硬编码环境判断
  • 5.5 敏感信息进仓库
  • 5.6 预发和生产配置不一致
• 六、环境区分速查表
• 七、小结
• 🔍 系列模块导航
  • 📝 工程化与协作规范
  • 📚 系列总览

同学们好，我是 Eugene（尤金），一名多年中后台前端开发工程师。

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

很多前端开发者都会遇到一个瓶颈：

代码能跑，但不够规范；功能能实现，但维护起来特别痛苦；一个人写没问题，一到团队协作就各种混乱、踩坑、返工。

想写出干净、优雅、可维护的专业代码，靠的不是天赋，而是体系化的规范 + 真实实战经验。

这一系列《前端规范实战》，我会用大白话 + 真实业务场景，不讲玄学、不堆理论，只分享能直接落地的规范、标准与避坑指南。

帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。

工作几年后，不少人依然对「开发环境」「测试环境」「预发环境」「生产环境」的概念和用法模糊，甚至混用。配置不当往往导致：接口打到生产、日志泄露敏感信息、调试代码上线等问题。

一、四个环境到底在干什么？

先把几个概念说清楚。

1.1 dev（开发环境）

• 作用：本地开发、联调、自测
• 使用者：前端/后端开发者
• 特点：
  • 本地或内网服务器
  • 有热更新、Source Map
  • 可随意打 console.log
  • 接口指向开发/测试后端

⬆ 返回目录

1.2 test（测试环境）

• 作用：QA 测试、联调、验收
• 使用者：测试、产品、开发
• 特点：
  • 有独立域名（如 test.xxx.com）
  • 接口指向测试后端
  • 数据以测试数据为主

⬆ 返回目录

1.3 pre（预发 / 预生产环境）

• 作用：上线前最后一次验证，尽量贴近生产
• 使用者：测试、产品、少数开发
• 特点：
  • 和生产环境配置、后端、数据源尽量一致
  • 用生产配置验证逻辑
  • 一般没有真实用户流量

⬆ 返回目录

1.4 prod（生产环境）

• 作用：真实线上环境，对外提供服务
• 使用者：真实用户
• 特点：
  • 关闭调试、Source Map 等
  • 接口必须是生产 API
  • 避免输出敏感信息
  • 注重稳定与安全

⬆ 返回目录

二、为什么必须区分环境？

⬆ 返回目录

三、Vue 项目中如何配置多环境？

以 Vue CLI / Vite 两种常见方案说明。

3.1 方案一：Vue CLI（create-vue / @vue/cli）

约定用 .env.[mode] 区分环境，例如：

.env # 所有环境共用
.env.development # 开发环境
.env.test # 测试环境
.env.pre # 预发环境
.env.production # 生产环境

命名规则：

• development 对应 npm run dev
• production 对应 npm run build
• test、pre 需要单独指定 mode

示例目录结构

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

.env.development

# 开发环境
NODE_ENV=development
VUE_APP_BASE_API=http://dev-api.example.com
VUE_APP_ENV=dev
VUE_APP_ENABLE_MOCK=true

.env.test

# 测试环境
NODE_ENV=production
VUE_APP_BASE_API=https://test-api.example.com
VUE_APP_ENV=test
VUE_APP_ENABLE_MOCK=false

.env.pre

# 预发环境（尽量接近生产）
NODE_ENV=production
VUE_APP_BASE_API=https://pre-api.example.com
VUE_APP_ENV=pre
VUE_APP_ENABLE_MOCK=false

.env.production

# 生产环境
NODE_ENV=production
VUE_APP_BASE_API=https://api.example.com
VUE_APP_ENV=prod
VUE_APP_ENABLE_MOCK=false

说明：

• Vue CLI 中，只有以 VUE_APP_ 开头的变量会暴露给前端代码
• NODE_ENV 为 development 时启用热更新等开发特性
• test、pre 一般也用 NODE_ENV=production 做生产构建

package.json 脚本

{
"scripts": {
"dev": "vue-cli-service serve",
"build": "vue-cli-service build",
"build:test": "vue-cli-service build –mode test",
"build:pre": "vue-cli-service build –mode pre",
"build:prod": "vue-cli-service build –mode production"
}
}

在代码中使用

// src/api/request.js
const baseURL = process.env.VUE_APP_BASE_API
const isDev = process.env.VUE_APP_ENV === 'dev'

// 开发环境可以打印，生产不打印
if (isDev) {
console.log('当前环境:', process.env.VUE_APP_ENV)
}

⬆ 返回目录

3.2 方案二：Vite 项目

Vite 用 import.meta.env.MODE 和 .env.[mode] 管理环境。

示例目录结构

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

.env.development

NODE_ENV=development
VITE_BASE_API=http://dev-api.example.com
VITE_APP_ENV=dev
VITE_ENABLE_MOCK=true

.env.production

NODE_ENV=production
VITE_BASE_API=https://api.example.com
VITE_APP_ENV=prod
VITE_ENABLE_MOCK=false

说明：

• Vite 只暴露以 VITE_ 开头的变量
• 不要用 VUE_APP_，在 Vite 中无效

vite.config.js 配置 mode

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig(({ mode }) => ({
plugins: [vue()],
// 根据 mode 决定是否生成 sourcemap
build: {
sourcemap: mode === 'development',
minify: mode === 'production',
},
}))

package.json 脚本

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

在代码中使用

// src/api/request.js
const baseURL = import.meta.env.VITE_BASE_API
const isDev = import.meta.env.VITE_APP_ENV === 'dev'

⬆ 返回目录

四、统一封装：请求与接口切换

下面是一个统一的请求封装示例，展示如何根据环境切换接口和日志行为。

// src/utils/request.js

// 根据框架选择
const baseURL = process.env.VUE_APP_BASE_API || import.meta.env.VITE_BASE_API
const env = process.env.VUE_APP_ENV || import.meta.env.VITE_APP_ENV

const isProd = ['prod', 'pre'].includes(env)

// 创建 axios 实例
const request = axios.create({
baseURL,
timeout: 15000,
})

// 请求拦截器
request.interceptors.request.use(
(config) => {
// 生产/预发环境不打印完整请求信息
if (!isProd) {
console.log(`[${env}] 请求:`, config.url, config.params || config.data)
}
return config
},
(err) => Promise.reject(err)
)

// 响应拦截器
request.interceptors.response.use(
(res) => {
if (!isProd && res.config?.url) {
console.log(`[${env}] 响应:`, res.config.url, res.data)
}
return res.data
},
(err) => {
// 生产环境不把详细错误堆栈暴露给用户
if (isProd) {
console.error('请求失败') // 可接入监控
} else {
console.error('请求失败:', err.message, err.response)
}
return Promise.reject(err)
}
)

export default request

要点：

⬆ 返回目录

五、常见踩坑与规范

5.1 接口地址写死

错误示例：

// 千万别这样！
axios.get('https://api.example.com/user/list')

正确做法：

const baseURL = process.env.VUE_APP_BASE_API
axios.get(`${baseURL}/user/list`)

⬆ 返回目录

5.2 环境变量未生效

• Vue CLI：必须使用 VUE_APP_ 前缀
• Vite：必须使用 VITE_ 前缀
• 修改 .env 后需重启 dev 或重新 build

⬆ 返回目录

5.3 生产环境开启 Source Map

生产包若带完整 Source Map，源码易被还原，存在泄露风险。

// vite.config.js
export default defineConfig(({ mode }) => ({
build: {
sourcemap: mode !== 'production', // 仅非生产生成
// 或生产环境用 hidden，只给监控用
// sourcemap: mode === 'production' ? 'hidden' : true,
},
}))

⬆ 返回目录

5.4 在代码中硬编码环境判断

不推荐：

if (window.location.hostname === 'test.xxx.com') {
baseURL = 'https://test-api.xxx.com'
}

推荐：

统一用 .env + VUE_APP_* / VITE_*，构建时注入，避免运行时依赖域名。

⬆ 返回目录

5.5 敏感信息进仓库

• .env、.env.local 等若含密钥，应加入 .gitignore
• 生产环境密钥建议用 CI/CD 注入，而不是提交到仓库

⬆ 返回目录

5.6 预发和生产配置不一致

预发环境的价值在于「和生产一致」。若预发和生产使用不同 API 或配置，容易漏掉线上问题，建议：

• 预发和生产使用相同接口规范、鉴权方式
• 仅域名、部分开关等可配置差异

⬆ 返回目录

六、环境区分速查表

⬆ 返回目录

七、小结

实践上：

• 用 .env.[mode] + 环境变量统一管理接口和开关
• 不在代码中写死 API、密钥、环境判断
• 生产环境关闭 Source Map、控制日志输出
• 敏感配置不进仓库，通过 CI/CD 注入

按以上规范配置，能明显减少「打到错误环境」「调试代码上线」「配置泄露」等问题，把环境区分清楚，是工程化与协作的基础一步。

⬆ 返回目录

🔍 系列模块导航

📝 工程化与协作规范

一、《Vite 工程化实战：alias/env/proxy/ 打包配置全解析，统一项目规范避坑｜工程化与协作规范篇》 二、《前端多环境配置规范：dev/test/pre/prod 环境差异与配置，避免生产环境踩坑｜工程化与协作规范篇》 三、《前端 Git 协作规范实战：commit message + 分支管理 + 合并流程，告别冲突与混乱｜工程化与协作规范篇》 四、《ESLint + Prettier 实战：统一前端代码风格，自动修复语法格式问题｜工程化与协作规范篇》 五、《Element Plus/VXE-Table UI 组件库规范：统一用法实战，避开样式冲突与维护混乱｜工程化与协作规范篇》

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

📚 系列总览

前端体系化学习完全体：基础 → 规范 → 架构 → 大厂面试 四套系列、百余篇高质量实战文，从入门到进阶，一站式补齐前端核心能力

• 前端基础实战系列： 《前端基础实战：JS/TS与Vue体系化扫盲（47 篇完整目录 + 避坑）》
• 前端规范实战系列： 《JS/TS/Vue 前端规范实战：从写对到写优，搞定中后台规范落地，打造可维护代码（40 篇全目录）》
• 前端架构实战系列：聚焦工程化、性能优化、可维护架构、中后台体系设计（持续更新中）
• 前端大厂面试系列：覆盖高频考点、手写题、项目深挖、简历与面试技巧（规划中）

每个系列完结后，都会整理成一篇完整导航文并附上直达链接，方便大家按顺序、体系化学习。

全套内容持续更新中，敬请期待～

⬆ 返回目录

技术成长，从来不是比谁写得快，而是比谁写得稳、规范、可维护。

哪怕每次只吃透一条规范，长期下来，差距会非常明显。

后续我会持续更新前端规范、工程化、可维护代码相关实战干货，帮你告别面条代码、维护噩梦，在开发与面试中更有底气。

觉得有用欢迎 点赞 + 收藏 + 关注，不错过每一篇实战内容。

我是 Eugene，与你一起写规范、写优质代码，我们下篇干货见～