Redwood 环境变量完全指南：Web 端与 API 端的加载、注入与安全实践

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载Redwood 应用由 APINode.js 目标与 Web浏览器目标两个固定 Side 组成二者获取环境变量的方式截然不同。本文基于 Redwood 6.x 官方文档 environment-variables.md 展开系统讲解.env与.env.defaults的加载机制、Web 端两种构建期变量注入方案redwood.toml的includeEnvironmentVariables与REDWOOD_ENV_前缀、API URL 的全局注入、开发期FatalErrorPage编辑器配置以及敏感信息保护并结合仓库源码印证其底层实现让你能按环境正确配置、安全使用环境变量。总览Redwood 的两种 Side、两种加载路径Redwood 应用有两个固定的 Side各自有唯一的目标运行环境API Side目标为 Node.js可以直接通过process.env.VAR_NAME在服务端代码Functions、Services、GraphQL 解析器等中读取环境变量Web Side目标为浏览器没有process.env这个概念必须依赖构建期替换build-time replacement把变量值烘焙进静态产物。所有环境变量文件的加载都基于 dotenv 生态。具体来说Redwood 使用的是 dotenv-defaults因此同时支持加载.env和.env.defaults两个文件.env存放真实值通常不入库.env.defaults存放可提交到版本库的默认值/示例值。dotenv 的完整语法规则如多行值、引号与转义可参考其官方 Rules 章节。在 Web SideRedwood 还额外配置了 Vite将所有对process.env变量的引用在构建期替换为变量的实际值——这正是浏览器端能看到环境变量的根本机制。环境变量文件从何而来CLI 入口与加载顺序为了让.env与.env.defaults中的变量进入process.env必须在某个入口调用 dotenv 的config函数。在 Redwood 中这个入口就是CLI每次运行yarn rw命令时都会加载。文档中给出的经典实现位于packages/cli/src/index.jsimport { config } from dotenv-defaults config({ path: path.join(getPaths().base, .env), encoding: utf8, defaults: path.join(getPaths().base, .env.defaults), })在当前的仓库中这一职责已演进为packages/cli-helpers/src/lib/loadEnvFiles.ts中的loadEnvFiles()与loadDefaultEnvFiles()加载逻辑更完整export function loadDefaultEnvFiles(cwd: string) { dotenvDefaultsConfig({ path: path.join(cwd, .env), defaults: path.join(cwd, .env.defaults), multiline: true, }) }实际加载顺序为loadDefaultEnvFiles(base)加载.env与.env.defaultsdotenv-defaults 保证.env中的值优先于.env.defaultsloadNodeEnvDerivedEnvFile(base)若存在NODE_ENV则继续加载.env.${NODE_ENV}如.env.production并覆盖已有值loadUserSpecifiedEnvFiles(base, loadEnvFiles)若命令行带有--load-env-files suffix参数则加载对应的.env.suffix并覆盖。整个加载过程由process.env.REDWOOD_ENV_FILES_LOADED标记保证只执行一次参见 loadEnvFiles.ts。注意如果yarn rw dev已经在运行修改.env文件后本地应用不会立即生效必须停止并重新运行yarn rw dev。Web Side让浏览器访问环境变量的两种方案Heads Up要让 Web Side 在生产环境访问环境变量必须配置下面两种方案之一。Redwood 官方推荐Option 1redwood.toml的includeEnvironmentVariables因为它最健壮。Option 1redwood.toml中的includeEnvironmentVariables在redwood.toml的[web]段落中把需要暴露给 Web 端的变量名加入数组[web] includeEnvironmentVariables [SECRET_API_KEY, ANOTHER_ONE]加入该数组后这些变量在生产构建中会通过process.env.SECRET_API_KEY被替换为实际值。源码层面该替换由 Vite 插件完成packages/vite/src/lib/envVarDefinitions.ts会为每个列出的变量同时生成import.meta.env.${envName}与process.env.${envName}两条定义见 envVarDefinitions.ts从而保证代码中两种写法都能在构建期完成替换。Option 2REDWOOD_ENV_前缀在.env中只要变量名以REDWOOD_ENV_开头就会被自动注入 Web 端REDWOOD_ENV_MY_VAR_NAMEsome value代码中通过process.env.REDWOOD_ENV_MY_VAR_NAME访问构建期同样会被动态替换为实际值。envVarDefinitions.ts中遍历process.env所有键凡以REDWOOD_ENV_开头的都会生成import.meta.env与process.env两条替换定义见 envVarDefinitions.ts。安全警示浏览器端的明文暴露无论采用哪种方案凡是注入 Web 端的变量最终都会以明文形式存在于静态 JS/HTML 产物中。任何人查看你站点的源码都可能看到REDWOOD_ENV_SECRET_API_KEY的真实值。这是向浏览器交付静态 JS 与 HTML 这一模型固有的限制。因此只向 Web 端暴露非敏感的公开配置如 API 域名、公钥、站点标题等真正的密钥数据库密码、签名私钥、第三方 Secret只应保留在 API Side各认证提供商在setup命令的提示中也反复强调这一原则——例如 Clerk 的 setupHandler.ts 会提醒你把CLERK_PUBLISHABLE_KEY加入includeEnvironmentVariables而 Firebase 的 setupHandler.ts 则提示加入FIREBASE_API_KEY与FIREBASE_AUTH_DOMAIN——这些都是公开也安全的发布型密钥。与redwood.toml其他配置的配合includeEnvironmentVariables在redwood.toml中的完整定义与apiUrl、apiGraphQLUrl等键同属[web]段默认值为[]。若部署在不同环境需要不同的apiUrlredwood.toml本身也支持${envVar:[fallback]}插值语法详见 app-configuration-redwood-toml.md[web] title App running on ${APP_TITLE} port ${PORT:8910} apiUrl ${API_URL:/.redwood/functions} includeEnvironmentVariables []两点提醒fallback 值始终是字符串这些值在构建期完成插值。这与 Web 端环境变量构建期替换的特性一致。Web SideAPI URL 的全局注入Redwood 会自动把redwood.toml中[web]段落的 API URL 配置暴露到全局对象window或global上无需任何额外配置redwood.tomlkeyAvailable globally asDescriptionapiUrlglobal.RWJS_API_URLURL 或绝对路径指向 api-serverapiGraphQLUrlglobal.RWJS_API_GRAPHQL_URLURL 或绝对路径指向 GraphQL Function例如global.RWJS_API_GRAPHQL_URL给出 GraphQL endpoint 的完整地址。在redwood.toml中apiGraphQLUrl的默认值是${apiUrl}/graphql参见 app-configuration-redwood-toml.md。从源码看packages/vite/src/lib/envVarDefinitions.ts的RWJS_ENV段正是从配置中派生这两个全局变量RWJS_ENV: { RWJS_API_GRAPHQL_URL: rwConfig.web.apiGraphQLUrl ?? rwConfig.web.apiUrl /graphql, RWJS_API_URL: rwConfig.web.apiUrl, // ... }默认配置下apiUrl /.redwood/functions因此 GraphQL endpoint 默认为/.redwood/functions/graphql。开发期增强FatalErrorPage 与编辑器跳转Redwood 内置了FatalErrorPage当前版本实现于packages/web/src/components/DevFatalErrorPage.tsx当开发环境出错时会展示堆栈信息与请求详情帮助快速定位问题。注意FatalErrorPage不会被打包进生产构建仅用于开发调试。堆栈跟踪中的源码文件链接会尝试用你的编辑器打开默认使用 VSCode。你可以通过设置环境变量覆盖编辑器REDWOOD_ENV_EDITORvscode在源码中DevFatalErrorPage.tsx通过RWJS_DEBUG_ENV.REDWOOD_ENV_EDITOR || vscode读取该值见 DevFatalErrorPage.tsx而envVarDefinitions.ts则将其放入RWJS_DEBUG_ENV供开发期使用见 envVarDefinitions.ts。可以设置为vscode、webstorm、sublime、atom等编辑器对应的 scheme。API Side开发与生产开发环境API Side 在开发中可直接读取.env与.env.defaults中定义的变量用法就是标准的process.env.VAR_NAME。例如在.env中定义HELLO_ENVhello world然后生成一个 hello Functionyarn rw generate function hello并在响应体里引用该变量export const handler async (event, context) { return { statusCode: 200, body: ${process.env.HELLO_ENV}, } }启动开发服务后访问 http://localhost:8911/hello可以看到 Function 成功读取了环境变量并返回hello world。生产环境生产环境中环境变量由你部署的平台注入到 serverless 运行时。不同平台有各自的配置入口例如 Netlify 是在Settings Build Deploy Environment中设置。需要阅读对应托管商的文档完成配置。需要特别留意部分托管商区分构建环境与运行时环境。对此 Redwood 给出了明确的配置建议Web Side的变量属于构建期注入应配置为build-time variablesAPI Side的变量属于运行时读取应配置为runtime variables。配置错位会导致生产环境读不到变量这是实际部署中最常见的坑之一。保护敏感信息.env不入库.env通常包含敏感信息永远不要提交到版本库。实际上 Redwood 项目的默认.gitignore已经显式忽略了.env你几乎需要刻意为之才会误提交.DS_Store .env .netlify dev.db dist dist-babel node_modules yarn-error.log与之相对.env.defaults是用于存放默认值/示例值的文件可以安全提交便于团队协作时让每个人都有一套可运行的基线配置。小结一套按 Side 与环境落地的配置心法场景方式时机API 开发环境.env/.env.defaults直接写入process.env.VAR_NAME读取运行时每次yarn rw加载API 生产环境托管平台控制台配置如 Netlify Build Deploy Environment运行时配置为 runtime variablesWeb 生产环境方案一redwood.toml的[web].includeEnvironmentVariables数组构建期替换Web 生产环境方案二变量名加REDWOOD_ENV_前缀构建期替换API URL 注入自动global.RWJS_API_URL/global.RWJS_API_GRAPHQL_URL构建期派生开发期编辑器跳转.env中设置REDWOOD_ENV_EDITOR仅开发环境生效核心结论密钥只进 API公开配置才进 WebWeb 端变量按构建期替换来设计API 端变量按运行时读取来设计.env永不入库/api密钥永不暴露给浏览器。理解了加载入口packages/cli-helpers/src/lib/loadEnvFiles.ts与替换机制packages/vite/src/lib/envVarDefinitions.ts之后你就掌握了 Redwood 环境变量从文件到运行时的完整链路。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐Redwood 环境变量完全指南Web 端与 API 端的环境变量加载、注入与安全实践Redwood 环境变量完全指南Web 端与 API 端的环境变量加载、注入与安全实践 Redwood 应用由 APINode.js与 Web浏览器两后端前端Web框架开发工具Redwood 环境变量完全指南Web 端与 API 端的配置、注入与安全实践Redwood 环境变量完全指南Web 端与 API 端的配置、注入与安全实践 本文基于 Redwood 框架 v4.x 官方文档《Environment V后端前端Web框架开发工具Redwood 环境变量完全指南Web 与 API 双端的配置、注入与安全实践Redwood 环境变量完全指南Web 与 API 双端的配置、注入与安全实践 RedwoodRedwoodGraphQL将应用划分为 APINode.后端前端Web框架开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考