Razzle项目环境变量配置完全指南

邱晋力

于 2025-06-04 09:00:08 发布

阅读量349

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00036/article/details/148415006

Razzle项目环境变量配置完全指南

razzle ✨ Create server-rendered universal JavaScript applications with no configuration 项目地址: https://gitcode.com/gh_mirrors/ra/razzle

前言

在现代前端开发中，环境变量管理是项目配置的重要环节。Razzle作为一款优秀的同构(Isomorphic)React应用框架，提供了完善的环境变量支持机制。本文将全面解析Razzle中的环境变量系统，帮助开发者掌握构建时和运行时环境变量的使用技巧。

构建时环境变量

构建时变量是指在项目构建过程中被嵌入到代码中的环境变量，这些变量在应用运行时将不可更改。

核心构建变量

Razzle预定义了一系列构建时环境变量：

路径相关变量
- RAZZLE_PUBLIC_DIR：服务器文件系统中public目录的绝对路径
- RAZZLE_ASSETS_MANIFEST：包含编译后资源输出的文件路径
- REACT_BUNDLE_PATH：开发环境下React包的相对路径（影响错误覆盖层功能）
服务器配置
- PORT：服务器监听端口，默认为3000
- HOST：服务器绑定IP，默认为0.0.0.0（所有可用地址）
构建类型
- NODE_ENV：开发(development)或生产(production)环境标识
- BUILD_TYPE：应用类型，iso(同构应用)或spa(单页应用)，默认为iso
- BUILD_TARGET：构建目标，client或server
资源路径
- PUBLIC_PATH：客户端资源(JS/CSS/图片)的公共路径，支持CDN配置
- CLIENT_PUBLIC_PATH：开发环境下客户端构建的特殊公共路径

自定义构建变量

开发者可以创建自定义构建变量，但必须遵循以下规则：

变量名必须以RAZZLE_开头
修改后需要重启开发服务器才能生效

示例：

// 定义RAZZLE_API_BASE=xxx后，代码中可通过以下方式访问
const apiBase = process.env.RAZZLE_API_BASE;

运行时环境变量

运行时变量是指在应用运行时才确定的变量值，这类变量不会被打包进构建产物。

运行时变量处理策略

由于同构应用的特殊性，运行时变量在服务器和客户端环境的表现不同：

服务器端：可通过process.env直接访问
客户端：默认不可访问，需要特殊处理

推荐的处理方案：

创建配置文件

// config.js
export const runtimeConfig = typeof window !== 'undefined' ? {
  // 客户端配置
  apiUrl: window.env.apiUrl
} : {
  // 服务端配置
  apiUrl: process.env.API_URL
};

服务端注入到HTML

// server.js
res.send(`
  <!doctype html>
  <html>
    <body>
      <script>
        window.env = ${serialize(runtimeConfig)};
      </script>
    </body>
  </html>
`);

安全注意事项

使用serialize-javascript等库防止XSS攻击
避免将敏感信息暴露给客户端
客户端需要的变量应明确列入白名单

环境变量设置方式

临时变量（Shell会话级）

Windows (cmd.exe)

set RAZZLE_API_URL=http://api.example.com&&npm start

Linux/macOS (Bash)

RAZZLE_API_URL=http://api.example.com npm start

永久变量（项目级）

在项目根目录创建.env文件：

RAZZLE_API_URL=http://api.example.com
RAZZLE_DEBUG=true

变量扩展

.env文件支持变量扩展功能：

扩展系统变量

RAZZLE_VERSION=$npm_package_version

扩展文件内变量

DOMAIN=example.com
RAZZLE_API_URL=$DOMAIN/api

环境文件优先级

Razzle支持多环境配置文件，加载优先级如下：

开发环境(npm start)
- .env.development.local > .env.development > .env.local > .env
生产环境(npm run build)
- .env.production.local > .env.production > .env.local > .env
测试环境(npm test)
- .env.test.local > .env.test > .env

最佳实践

敏感信息管理
- 永远不要将敏感信息提交到版本控制
- 将.env*.local添加到.gitignore
- 使用CI/CD系统的安全变量存储

类型安全

考虑使用TypeScript类型定义环境变量

declare namespace NodeJS {
  interface ProcessEnv {
    RAZZLE_API_URL: string;
    RAZZLE_DEBUG?: string;
  }
}

文档维护
- 创建.env.example文件记录所有可用变量
- 为团队编写环境变量使用说明文档

常见问题解答

Q: 为什么我的环境变量修改后不生效？ A: 构建时变量修改后需要重启开发服务器；运行时变量修改后需要重启应用。

Q: 如何在客户端安全地使用API密钥？ A: 应该通过服务端代理访问敏感API，而不是将密钥暴露给客户端。

Q: 不同环境如何管理不同的配置？ A: 使用.env.development、.env.production等环境特定文件，并确保正确设置NODE_ENV。

总结

Razzle的环境变量系统为同构应用开发提供了灵活的配置方案。通过合理使用构建时和运行时变量，开发者可以轻松管理不同环境的配置差异。掌握本文介绍的各种技巧后，你将能够构建出更加专业、安全的Razzle应用。

razzle ✨ Create server-rendered universal JavaScript applications with no configuration 项目地址: https://gitcode.com/gh_mirrors/ra/razzle

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考