如何在React Vite项目中使用环境变量设置应用标题

问题根源 #

• Vite不兼容Create React App的REACT_APP_前缀规则，客户端可访问的环境变量必须以VITE_开头
• Vite运行环境中不存在process.env全局对象，直接调用会触发运行时错误，导致页面空白

正确实现步骤 #

1. 遵循Vite的环境变量命名规范 #

所有需要在客户端代码中读取的环境变量，必须以VITE_作为前缀，例如VITE_APP_TITLE

2. 不同环境的配置方式 #

开发环境（本地启动）

有两种配置方式可选：

• 临时会话配置（仅当前终端会话有效）

  # macOS/Linux
  VITE_APP_TITLE="我的开发标题" npx vite --host
  # Windows PowerShell
  $env:VITE_APP_TITLE="我的开发标题"; npx vite --host
  # Windows CMD
  set VITE_APP_TITLE="我的开发标题" && npx vite --host
  

• 持久化配置（通过.env文件）
  在项目根目录创建.env文件，写入：

  VITE_APP_TITLE="我的开发标题"
  

  启动项目时Vite会自动加载该文件中的变量

测试/生产构建环境

• 创建对应环境的专属.env文件：
  • 测试环境：.env.test
  • 生产环境：.env.production
    示例（.env.production内容）：

  VITE_APP_TITLE="我的生产标题"
  

• 构建时指定环境模式：

  # 测试环境构建
  vite build --mode test
  # 生产环境构建（默认模式为production，可省略参数）
  vite build
  

3. 代码中正确获取环境变量 #

替换错误的process.env或REACT_APP_前缀写法，使用Vite提供的import.meta.env：

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

// 动态设置文档标题
document.title = import.meta.env.VITE_APP_TITLE || '默认标题';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

4. 可选优化：组件内动态设置标题 #

如果需要在组件生命周期或路由切换时更新标题，可使用useEffect：

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    document.title = import.meta.env.VITE_APP_TITLE || '默认标题';
  }, []);

  return <div>你的应用内容</div>;
}

export default App;

5. 可选：直接在index.html中插值 #

Vite支持在index.html中直接插入环境变量，无需编写JS代码：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- 直接插入环境变量，默认值可通过模板语法实现 -->
    <title>%VITE_APP_TITLE% || 默认标题</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

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