迁移ParcelJS构建的React应用到TS/React时遇process环境变量报错

我之前帮朋友处理过一模一样的问题，其实这个报错的根源很明确：TypeScript编译器不认识全局的process变量，但Parcel在构建阶段已经自动把process.env替换成了实际的环境变量值，所以浏览器能正常运行，只是终端会抛出类型检查错误而已。

下面给你几个可行的解决方法，按推荐优先级排序：

方法1：安装Node.js类型定义（最简单快速） #

TypeScript默认没有内置Node.js环境的全局变量类型，我们只需要安装@types/node这个类型包，就能让TS识别process对象：

npm install @types/node --save-dev
# 或者用yarn/pnpm
yarn add @types/node -D
pnpm add @types/node -D

安装完成后，重新运行项目，终端的Cannot find name 'process'报错应该就消失了。

方法2：手动声明环境变量类型（更严谨） #

如果不想额外安装依赖，可以在项目的src目录下新建一个env.d.ts（或任意.d.ts后缀的声明文件），手动给process.env添加类型定义：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      // 这里列出你用到的所有环境变量，指定类型
      URL: string;
      // 比如还有其他变量的话，像API_KEY: string;
    }
  }
}

// 必须加这行，不然TS会把这个文件当成脚本而不是模块
export {};

这样不仅能解决报错，还能让TS给你的环境变量提供自动补全提示，类型检查更严格。

方法3：改用Parcel推荐的import.meta.env（更现代） #

Parcel官方现在更推荐使用ES模块标准的import.meta.env来替代process.env，这是浏览器原生支持的写法，TypeScript天生就能识别，完全不会有类型问题：

1. 把代码里的process.env替换成import.meta.env：

url: `${import.meta.env.URL}/checkout`,

2. 在你的环境变量文件（比如.env、.env.development）里定义变量：

URL=https://your-api-domain.com

Parcel会自动处理这些变量，构建时替换成实际值，而且TS不会再抛出任何类型错误，这也是长远来看最规范的写法。

额外小提示 #

• 注意：如果是敏感的环境变量（比如密钥），不要直接暴露在客户端代码里，Parcel会把所有import.meta.env或process.env的变量打包到客户端，所以只放公开的配置项。
• 如果你用的是Parcel 2.x版本，确保你的tsconfig.json里的compilerOptions.module设置为ESNext或ES6，这样TS能更好地支持import.meta.env。

试一下上面的方法，应该就能彻底解决你的问题啦～

内容的提问来源于stack exchange，提问作者Kleioz