告别 `process is not defined`：从环境差异到构建工具适配的实战指南-优快云博客

1. 为什么浏览器不认识 `process`？从根源理解环境差异

我猜很多前端开发者都遇到过这个让人头疼的错误：Uncaught ReferenceError: process is not defined。页面一片空白，控制台红彤彤的，第一反应往往是“我的代码明明在Node.js里跑得好好的啊！” 这其实是一个典型的“水土不服”问题。你的代码从一个环境搬到了另一个环境，有些“本地特产”自然就找不到了。

要彻底告别这个错误，我们得先搞清楚 process 这位老兄到底是谁，它从哪来，又为什么在浏览器里“查无此人”。简单来说，process 是 Node.js 运行时环境 提供的一个全局对象，你可以把它看作是Node.js这个“操作系统”给JavaScript代码开的一个后门。通过这个后门，你的代码可以跟Node.js运行时进行深度交互，比如读取环境变量（process.env）、获取命令行参数、操作标准输入输出流，甚至控制进程本身。它是Node.js作为服务器端运行时能力的核心体现。

而浏览器环境则完全是另一番天地。浏览器里的JavaScript运行在一个被严格“沙箱化”的环境里，它的核心使命是操作DOM、处理用户交互、发起网络请求。浏览器出于安全和稳定性的考虑，绝不会向你的脚本暴露类似系统进程、文件系统这样的底层接口。所以，浏览器全局对象是 window，而不是 process。当你写了一段既想在Node.js后端跑，又想在前端浏览器里用的“同构”代码，或者直接引用了某个以为 process 无处不在的第三方库时，这个错误就会跳出来给你上一课。

理解这个根本差异至关重要。这不仅仅是换一个变量名（比如从 process.env 换成 import.meta.env）那么简单。它意味着你的开发思维需要根据目标环境进行切换：在Node.js里，你可以“为所欲为”地访问系统资源；在浏览器里，你必须遵守“沙箱”的规则，所有与外部世界的交互都要通过浏览器提供的安全API（如fetch、localStorage）来进行。很多构建工具的工作，本质上就是在帮你弥合这两种环境之间的鸿沟，让你能用一套接近Node.js的写法，最终产出符合浏览器安全规范的代码。

2. 构建工具的角色：环境变量的“搬运工”与“转换器”

既然浏览器原生不支持 process.env，那我们项目里用的环境变量是怎么跑到前端代码里去的呢？答案就是构建工具。你可以把Webpack、Vite这些工具想象成高级的“代码搬运工”和“格式转换器”。它们的工作流程大致是这样的：你在项目根目录下创建一个 .env 文件，里面写上 VITE_API_BASE_URL=https://api.example.com。在开发或构建时，构建工具会读取这个文件，然后把里面的键值对，以一种浏览器能理解的方式，“注入”到你的源代码中。

但不同的“搬运工”有不同的“搬运哲学”和“打包方式”，这就导致了适配方案的差异。Vite 的设计理念是“原生ES模块优先”和更快的开发体验。它明确摒弃了Node.js风格的 process.env，转而拥抱ES模块标准的 import.meta.env。这是一种“破旧立新”的做法，鼓励开发者使用更现代的、浏览器友好的API。而 Webpack 作为老牌且功能强大的构建工具，它的哲学是“兼容并包”。它通过 DefinePlugin 这个插件，在构建阶段进行全局文本替换，硬生生地把 process.env.XXX 这样的代码替换成对应的静态值，从而模拟出Node.js环境的存在，这是一种“修旧如旧”的适配策略。

选择哪种工具，不仅影响你解决 process is not defined 错误的方式，更会影响你整个项目的配置思维和开发体验。Vite的方案更简洁、更面向未来，但可能需要你改变一些旧有的习惯；Webpack的方案更灵活、生态更庞大，但配置起来可能更复杂。理解它们背后的原理，能帮助你在遇到问题时，不再只是机械地复制粘贴配置代码，而是能清晰地知道每一步操作是在解决哪个环节的问题。

3. Vite 项目实战：拥抱 `import.meta.env`

如果你正在使用Vite，那么恭喜你，解决 process is not defined 的路径非常清晰——彻底告别 process，投入 import.meta.env 的怀抱。这不是一个可选项，而是Vite生态下的强制规范。Vite在开发服务器和构建过程中，都会自动加载你的环境变量文件，并将它们挂载到 import.meta.env 这个对象上。

第一步，正确设置环境变量文件。 Vite默认会从项目根目录读取 .env、.env.local、.env.[mode] 等文件。这里有个关键点：为了安全，Vite规定只有以 VITE_ 开头的变量才会被暴露给前端代码。这是为了防止你意外地将服务器密钥等敏感信息发送到浏览器。所以，你的 .env 文件应该长这样：

VITE_APP_TITLE=我的Vite应用
VITE_API_BASE_URL=https://api.myapp.com
VITE_DEBUG_MODE=true

像 DATABASE_PASSWORD 这样的变量，就不要加 VITE_ 前缀，它们不会被注入。

第二步，在代码中引用。 接下来，在你的Vue、React或纯JavaScript模块中，你就可以直接使用了：

// 在Vue组件或任何JavaScript模块中
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
const appTitle = import.meta.env.VITE_APP_TITLE;

console.log(`应用标题：${appTitle}`); // 输出：应用标题：我的Vite应用
fetch(`${apiBaseUrl}/users`)
  .then(response => response.json())
  .then(data => console.log(data));

注意，import.meta.env 是一个完全静态的对象，它的属性在构建时就被替换成了字符串字面量。这意味着你不能动态地访问属性，比如 import.meta.env[‘VITE_’ + varName] 是不行的。

第三步，处理路由基础路径。 在原始文章的例子中，错误源于 createWebHistory(process.env.BASE_URL)。在Vite中，你需要使用 import.meta.env.BASE_URL。这个 BASE_URL 是Vite内置的一个特殊变量，它对应的是 vite.config.js 中的 base 配置项，或者你在构建时指定的基础公共路径。所以正确的路由配置应该是：

import { createRouter, createWebHistory } from 'vue-router';
// ... 导入你的组件

const router = createRouter({
  // 使用 import.meta.env.BASE_URL
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
});

如果你没有特殊配置，import.meta.env.BASE_URL 默认是 /，这样配置也是完全正确的。

我实测下来，只要遵循 VITE_ 前缀的命名规范，并在代码中统一使用 import.meta.env，在Vite项目中就几乎不会再遇到环境变量相关的问题了，整个过程非常顺畅。

4. Webpack 项目实战：使用 DefinePlugin 模拟环境

对于Webpack项目，思路就完全不同了。Webpack不会自动为你创建一个类似 import.meta.env 的新对象，它的策略是：既然你的代码里写的是 process.env.XXX，那我就在打包的时候，把这段代码直接替换成对应的值。这个“偷梁换柱”的工作，就是由 webpack.DefinePlugin 插件完成的。

配置 DefinePlugin。 你需要在 webpack.config.js 文件中进行配置。这里有个非常重要的细节：插件期望的值是一个代码片段，而不是一个字符串。为了确保替换进去的是一个字符串字面量，我们通常需要用 JSON.stringify() 再包裹一层。

// webpack.config.js
const webpack = require('webpack');
const dotenv = require('dotenv').config(); // 可选，用于读取.env文件

module.exports = {
  // ... 其他配置（entry, output, module等）
  plugins: [
    new webpack.DefinePlugin({
      // 关键在这里：将 ‘process.env.BASE_URL‘ 替换为实际值
      ‘process.env.BASE_URL‘: JSON.stringify(process.env.BASE_URL || ‘/‘),
      // 你可以定义多个环境变量
      ‘process.env.NODE_ENV‘: JSON.stringify(process.env.NODE_ENV || ‘development‘),
      ‘process.env.API_URL‘: JSON.stringify(process.env.API_URL || ‘https://dev.api.com‘)
    })
  ]
};

上面这个配置的意思是：在Webpack构建时，它会去读取当前Node.js进程的环境变量（即运行 webpack 命令时的环境），然后将你源代码中所有出现的 process.env.BASE_URL 字面量，直接替换成比如 “/my-app/” 这样一个字符串。替换完成后，浏览器里运行的代码中根本就没有 process.env 这个对象了，有的只是一个已经被替换好的静态字符串，所以自然不会报错。

与 dotenv 等工具配合。 在实际开发中，我们通常不会直接在命令行中设置一堆 BASE_URL=xxx，而是使用 .env 文件。你可以使用 dotenv 这样的npm包，在Webpack配置文件的顶部加载环境变量：

require(‘dotenv‘).config({ path: ‘./.env.development‘ }); // 加载指定环境文件

然后，process.env.XXX 就能读取到 .env 文件里定义的值了。这样，你的Webpack配置就和你的环境文件关联起来了。

一个我踩过的坑： 注意 DefinePlugin 是做直接的文本替换。如果你写 ‘process.env.API_URL‘: process.env.API_URL，而 API_URL 的值是 https://api.com，那么替换后代码会变成 https://api.com，这会导致一个语法错误，因为它不是一个带引号的字符串。所以，务必记得用 JSON.stringify()，它会确保生成 “https://api.com” 这样的正确格式。

5. 跨环境代码的通用适配策略

有时候，我们写的代码或引用的库，需要同时在Node.js环境和浏览器环境（经过构建后）下运行。这时候，就不能只依赖某一种构建工具的特定方案了，需要一些更通用的适配技巧。

策略一：环境检测与兜底。 最朴素也最有效的方法，就是在使用 process 之前，先判断它是否存在。

// 通用适配代码
const baseUrl = (typeof process !== ‘undefined‘ && process.env && process.env.BASE_URL) 
  ? process.env.BASE_URL 
  : (import.meta.env && import.meta.env.BASE_URL) 
  ? import.meta.env.BASE_URL 
  : ‘/‘; // 最终兜底值

const router = createRouter({
  history: createWebHistory(baseUrl),
  // ... routes
});

这段代码会先检查Node.js的 process.env，再检查Vite的 import.meta.env，最后提供一个默认值。这样，无论代码在哪个环境被评估，都能得到一个有效的 baseUrl。

策略二：在构建时注入全局变量。 这是对Webpack DefinePlugin 思路的扩展，但使其更显式。你可以在你的入口文件（如 main.js）顶部，根据构建工具的不同，手动“伪造”一个 process 对象。

// main.js 或专门的 env.js
// 构建工具会在打包时，将 __BUILD_ENV__ 替换为实际值
const env = {
  BASE_URL: __BUILD_ENV__.BASE_URL || ‘/‘,
  NODE_ENV: __BUILD_ENV__.NODE_ENV || ‘development‘
};

// 如果不存在全局的 process，就创建一个模拟的
if (typeof process === ‘undefined‘) {
  window.process = { env };
} else {
  process.env = { ...process.env, ...env };
}

然后在Webpack或Vite的配置中，分别用 DefinePlugin 或 define 选项来定义 __BUILD_ENV__ 这个对象。这种方法把环境变量的来源集中到了一处，代码逻辑更清晰。

策略三：使用条件导入（Dynamic Import）。 对于差异较大的环境特定代码，可以考虑使用动态导入。

let routerConfig;
if (typeof window !== ‘undefined‘) {
  // 浏览器环境，使用基于 import.meta.env 或 window 变量的配置
  const browserConfig = await import(‘./router.browser.js‘);
  routerConfig = browserConfig;
} else {
  // Node.js 环境（如SSR），使用基于 process.env 的配置
  const serverConfig = await import(‘./router.server.js‘);
  routerConfig = serverConfig;
}
// 使用 routerConfig 创建路由

这种方式将不同环境的配置彻底分离，适合大型或复杂的同构应用。

选择哪种策略，取决于你的项目规模和复杂度。对于大多数中小型项目，策略一已经足够。如果你的代码库很庞大，或者是一个需要服务端渲染（SSR）的应用，策略二或三可能更利于维护。

6. 常见陷阱与深度排查指南

即使你按照上面的步骤操作了，有时候 process is not defined 这个幽灵还是会偶尔出现。别慌，我结合自己踩过的坑，给你梳理几个常见的排查方向。

陷阱一：第三方库的“锅”。 这是最常见的情况。你安装了一个库，它在内部偷偷使用了 process.env.NODE_ENV 来判断环境（很多库都这么干），但这个库的打包格式（UMD）可能没有处理好浏览器环境。解决方案是，检查这个库的文档，看它是否提供了浏览器专用的构建版本（通常是 *.browser.js 或 *.esm.js）。如果没有，你可能需要在其构建流程中，通过构建工具的配置（如Webpack的 externals 或 ProvidePlugin，Vite的 define）来为它提供 process.env.NODE_ENV 的模拟值。在Vite中，你可以在 vite.config.js 里这样配置：

// vite.config.js
export default defineConfig({
  define: {
    ‘process.env.NODE_ENV‘: JSON.stringify(process.env.NODE_ENV || ‘production‘)
  }
});

这相当于告诉Vite：“在打包时，如果看到 process.env.NODE_ENV，就把它替换成指定的字符串。” 注意，这只解决了 NODE_ENV 这一个变量，如果库用了其他 process.env 属性，你需要一并定义。

陷阱二：构建配置未生效。 尤其是Webpack项目，修改了 webpack.config.js 后，一定要重启开发服务器或者重新运行构建命令。有时候缓存会导致配置没有被重新加载。另外，检查你的环境变量文件（.env）是否放在了项目根目录，变量名是否正确，以及是否被 .gitignore 等文件意外排除。

陷阱三：代码中存在动态访问。 正如前面提到的，无论是Vite的 import.meta.env 还是Webpack的 DefinePlugin 替换，都是在静态分析阶段完成的。如果你的代码是动态拼接属性名来访问环境变量，比如：

const envKey = ‘VITE_‘ + ‘API_URL‘;
const url = import.meta.env[envKey]; // 这行会出问题！

构建工具无法在打包时确定 envKey 的值，因此无法进行替换，最终浏览器里 import.meta.env[‘VITE_API_URL‘] 会是 undefined。正确的做法是避免动态访问，或者将需要的环境变量提前赋值给局部变量。

深度排查工具： 当你实在找不到问题时，可以打开浏览器开发者工具，查看Sources面板中经过构建工具处理后的最终源代码。搜索 process.env 或 import.meta.env，看看它们是否已经被正确替换成了具体的字符串值。如果还能看到原始的变量名，那就说明构建工具的替换步骤没有生效，你需要回头仔细检查配置。

7. 现代前端框架的最佳实践演进

随着Vite的崛起和ES模块的普及，前端社区在处理环境变量和跨环境兼容性方面，已经形成了一些新的、更清晰的最佳实践。

拥抱 ES 模块标准。 Vite 推动的 import.meta.env 是一个积极的信号。它让环境变量的访问方式与 ES 模块标准对齐，减少了与 Node.js 特定 API 的耦合。在新的项目中，尤其是使用 Vite 作为构建工具时，我强烈建议从一开始就使用 import.meta.env，并遵循 VITE_ 前缀的约定。这能让你的项目更“未来友好”，也更容易被其他开发者理解。

类型安全。 在 TypeScript 项目中，import.meta.env 默认是没有类型提示的。为了获得更好的开发体验，你可以在 src 目录下创建一个 env.d.ts 文件，进行类型声明：

// src/env.d.ts
interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_BASE_URL: string
  readonly VITE_DEBUG_MODE: string // 注意，从.env读取的都是字符串
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

这样，你在代码中输入 import.meta.env. 时，编辑器就会自动提示出 VITE_APP_TITLE 等变量，并且有类型检查，避免了拼写错误。

环境配置分层。 不要把所有配置都塞进环境变量。将配置分层管理是更专业的做法：

构建时配置：通过 .env 文件管理，如 API 地址、功能开关。这些值在构建后是固定的。
运行时配置：对于可能需要动态变更的配置（比如根据用户身份切换主题），可以将其放在一个静态的 config.json 文件中，通过 fetch 在应用初始化时加载，或者托管在外部配置服务上。

SSR（服务端渲染）场景。 这是环境变量问题最复杂的场景。在SSR中，同一份代码会在Node.js服务器和浏览器客户端各执行一次。你必须确保环境变量在两端都能正确获取。通用的做法是，在服务器启动时，将需要的环境变量序列化，并注入到HTML模板中，作为 window.__INITIAL_STATE__ 这样的全局变量。然后，在客户端的入口代码中，优先从 window 上读取这个注入的值，作为 process.env 或 import.meta.env 的兜底。Nuxt.js、Next.js 等现代SSR框架已经帮你处理了大部分这类复杂性，了解其原理有助于你进行更底层的定制。

说到底，解决 process is not defined 不仅仅是一个错误修复，它更是一个契机，让你去深入理解前端工程化的核心——如何让代码适应不同的运行时环境。从最初的一行报错，到理清Node.js与浏览器的差异，再到根据构建工具选择适配方案，最后形成一套适合自己项目的环境管理策略，这个过程本身就是一次宝贵的学习和成长。