Redwood 环境变量完全指南Web 端与 API 端的配置、注入与安全实践【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood本文基于 Redwood 框架 v4.x 官方文档《Environment Variables》整理扩充系统讲解 Redwood 应用中环境变量的加载机制dotenv / dotenv-defaults、Web 端两种注入方式includeEnvironmentVariables与REDWOOD_ENV_前缀、API 端开发与生产环境的使用、API URL 的全局暴露以及敏感信息的安全防护并结合仓库源码CLI、Vite 插件、api-server验证每个环节的真实实现。Redwood 应用由固定的两个 Side 组成APINode.js 运行时与Web浏览器运行时它们分别拥有各自的环境变量注入方式且开发环境与生产环境的行为有所不同。本文将从变量从哪来、如何加载、如何注入到各端这条主线出发给出可直接落地的配置方案与可验证的源码依据。总体机制dotenv 与 dotenv-defaultsRedwood 应用使用 dotenv 将.env文件中的变量加载进process.env。dotenv 的语法规则如KEYvalue、#注释、多行值、引号处理等直接适用于你的.env文件可参考 dotenv 官方 README 的 Rules 章节。更准确地说Redwood 使用的是dotenv-defaults——这是 dotenv 的一个扩展它额外支持.env.defaults文件技术上我们使用的是 dotenv-defaults这也是我们加载并提供.env.defaults的方式。这意味着 Redwood 项目存在两层环境变量文件.env存放真实的环境变量通常包含敏感信息不应提交到版本库.env.defaults存放变量的默认值/占位值作为兜底当.env中未定义某变量时使用.env.defaults中的值。此外Redwood 还通过dotenv-webpack配置 Webpack使得 Web 端代码中对process.env变量的引用在构建期被替换为变量的实际值详见下文 Web 章节。环境变量文件在哪里加载CLI 入口源码在 v4.x 版本中dotenv 的config调用位于 CLI 入口——每当执行yarn rw命令时都会先加载环境变量import { config } from dotenv-defaults config({ path: path.join(getPaths().base, .env), encoding: utf8, defaults: path.join(getPaths().base, .env.defaults), })在现代版本的仓库中这一逻辑被封装为loadEnvFiles()在 packages/cli/src/index.js#L104-L107 中于设置cwd后尽早调用。其实际实现位于 packages/cli-helpers/src/lib/loadEnvFiles.tsexport function loadDefaultEnvFiles(cwd: string) { dotenvDefaultsConfig({ path: path.join(cwd, .env), defaults: path.join(cwd, .env.defaults), // ts-expect-error - Old typings. types/dotenv-defaults depends on dotenv // v8. dotenv-defaults uses dotenv v14 multiline: true, }) }其中multiline: true使.env文件支持多行值loadEnvFiles()还支持根据NODE_ENV自动加载.env.NODE_ENV如.env.production以及通过--load-env-files参数指定额外的.env.suffix文件。同理在生产服务器启动路径中packages/api-server/src/createServer.ts#L29-L37 也在模块加载时执行了等价的 dotenv-defaults 配置保证 API 侧在createServer之前就能读取环境变量。dotenv-defaults同时是redwoodjs/cli、redwoodjs/api-server、redwoodjs/structure等包的直接依赖见 packages/cli/package.json#L59。Web 端如何让浏览器代码拿到环境变量Web 端代码运行在浏览器中本身并没有process.env因此必须由构建工具在构建期把对process.env.XXX的引用替换成实际值。要覆盖这一点生产环境中必须选择下面两种方式之一二选一或并用。注意在开发环境Redwood 会替你处理大部分情况但要在生产环境让 Web 端访问环境变量你必须配置以下任一选项。Redwood 官方推荐方式一redwood.toml的includeEnvironmentVariables因为它最健壮。方式一redwood.toml 的 includeEnvironmentVariables在项目根目录的redwood.toml的[web]段中加入includeEnvironmentVariables数组[web] includeEnvironmentVariables [SECRET_API_KEY, ANOTHER_ONE]将环境变量加入该数组后它们在生产环境中即可通过process.env.SECRET_API_KEY在 Web 端访问。构建时Redwood 会移除process.env.SECRET_API_KEY这样的引用并将其替换为变量的实际值。从源码看这一替换在 Vite 构建管线中实现packages/vite/src/lib/envVarDefinitions.ts#L29-L41 会遍历rwConfig.web.includeEnvironmentVariables同时生成process.env.${envName}与import.meta.env.${envName}两份替换定义而 packages/vite/src/index.ts#L98-L103 中的redwood-plugin-vite-html-env插件还会对index.html中的%变量名%占位符做同样的替换。⚠️安全提醒如果有人查看你网站的源码他们可能以纯文本形式看到REDWOOD_ENV_SECRET_API_KEY。这是向浏览器交付静态 JS/HTML 的固有限制——任何注入到 Web 端 bundle 的变量都是可被查看的。因此不要把真正的服务端密钥放进 Web 端Web 端只应暴露公开配置如 API Key、发布用公钥等。方式二REDWOOD_ENV_ 前缀在.env文件中只要变量名以REDWOOD_ENV_开头就会被自动注入 Web 端REDWOOD_ENV_MY_VAR_NAMEsome value在代码中通过process.env.REDWOOD_ENV_MY_VAR_NAME访问构建期会被动态替换为实际值。与方式一相同这些变量在构建时也会被移除并替换为实际值以便在生产环境可用。源码依据packages/vite/src/lib/envVarDefinitions.ts#L43-L53 会遍历process.env中所有以REDWOOD_ENV_开头的变量并注入替换定义同时 packages/vite/src/lib/getMergedConfig.ts#L55 将 Vite 的envPrefix配置为REDWOOD_ENV_从构建工具层面保证了前缀变量的暴露。includeEnvironmentVariables与REDWOOD_ENV_前缀两种方式可以混用。相关的完整配置项说明可参见 app-configuration-redwood-toml.md 中关于[web]段的includeEnvironmentVariables描述。访问 API URL 的全局变量Redwood 会自动将redwood.toml中[web]段的 API URL 配置暴露为全局变量可以通过window或global对象访问。例如global.RWJS_API_GRAPHQL_URL即指向你的 GraphQL endpoint。redwood.toml键值与全局变量的映射关系如下redwood.toml键全局可用名说明apiUrlglobal.RWJS_API_URLapi-server 的 URL 或绝对路径apiGraphQLUrlglobal.RWJS_API_GRAPHQL_URLGraphQL function 的 URL 或绝对路径这两个全局变量的默认派生逻辑可在 packages/vite/src/lib/envVarDefinitions.ts#L10-L17 中看到RWJS_API_GRAPHQL_URL: rwConfig.web.apiGraphQLUrl ?? rwConfig.web.apiUrl /graphql, RWJS_API_URL: rwConfig.web.apiUrl,也就是说若未显式配置apiGraphQLUrlRedwood 会默认取apiUrl /graphql。在 v4.x 中redwood.toml的默认配置为[web] apiUrl /.redwood/functions includeEnvironmentVariables []默认情况下 GraphQL endpoint 为/.redwood/functions/graphql。更多细节见 app-configuration-redwood-toml.md 中的 API 路径api-paths一节其中也包含apiDbAuthUrldbAuth function 的 URL等衍生配置。开发环境致命错误页REDWOOD_ENV_EDITORRedwood 内置一个FatalErrorPage开发环境专用当出现错误时会展示有用的调试信息——包括堆栈轨迹与请求内容。FatalErrorPage在生产部署时不会被打包。堆栈轨迹中包含指向原始源文件的链接方便你快速在编辑器中打开对应文件。页面默认使用VSCode作为打开方式但你可以通过环境变量REDWOOD_ENV_EDITOR覆盖为其他编辑器REDWOOD_ENV_EDITORvscode例如要使用 VSCode Insider 版本可设置为vscode-insiders。源码依据packages/web/src/components/DevFatalErrorPage.tsx#L212-L217 中的toVSCodeURL函数读取RWJS_DEBUG_ENV.REDWOOD_ENV_EDITOR缺省值为vscode拼装形如vscode://file/路径:行:列的编辑器协议链接而REDWOOD_ENV_EDITOR由构建管线在 packages/vite/src/lib/envVarDefinitions.ts#L20 与 packages/vite/src/lib/registerFwGlobalsAndShims.ts#L89 注入到RWJS_DEBUG_ENV。API 端开发环境中的用法在开发环境中.env与.env.defaults中定义的变量可以直接通过process.env.VAR_NAME访问。例如在.env中定义HELLO_ENVhello world然后生成一个 hello Functionyarn rw generate function hello并在响应体中引用HELLO_ENVexport const handler async (event, context) { return { statusCode: 200, body: ${process.env.HELLO_ENV}, } }启动开发服务器后访问 http://localhost:8911/hello 即可看到该 Function 成功读取到环境变量响应体返回hello world。这是因为在开发环境中yarn rw dev启动的 API 服务器基于 Fastify见 packages/api-server/src/createServer.ts以及每个yarn rwCLI 命令都会先执行 dotenv 加载逻辑将.env内容注入process.env。API 端生产环境的配置生产环境中无论你部署到哪个平台该平台都会有特定的方式让环境变量对运行 Functions 的 serverless 环境可见。例如部署到 Netlify 时可在SettingsBuild DeployEnvironment中设置环境变量。由于平台差异较大请以你所选部署平台的官方文档为准。仓库中为各平台提供了相应的部署配置模板例如 packages/cli/src/commands/deploy/serverless.js 在部署前同样会调用 dotenv-defaults 加载.env确保构建与运行时环境变量一致。保护敏感信息永远不要提交 .env.env文件通常包含敏感信息永远不要提交到版本库。Redwood 默认在.gitignore中显式忽略了.env你不需要额外配置.DS_Store .env .netlify dev.db dist dist-babel node_modules yarn-error.log也就是说除非你刻意修改.gitignore否则git add .不会把.env加进暂存区。请把真实变量放在.env本地/部署平台秘密配置把不含敏感信息的默认值放在.env.defaults可安全提交作为团队共享的兜底。常见坑修改 .env 后不生效请记住如果yarn rw dev正在运行你本地应用不会立即反映对.env文件的修改需要先停止再重新运行yarn rw dev。原因在于环境变量是在 CLI 进程启动时一次性加载进process.env的见 packages/cli/src/index.js#L107 的loadEnvFiles()调用运行中的进程不会感知到文件变化。小结与最佳实践API 端.env/.env.defaults中的变量天然可通过process.env使用无需额外配置Web 端生产环境必须通过redwood.toml的includeEnvironmentVariables数组推荐或REDWOOD_ENV_前缀显式暴露变量安全边界Web 端所有变量都会以明文出现在静态资源中只放公开配置服务端密钥只留给 API 端编辑器调试用REDWOOD_ENV_EDITOR自定义开发错误页的编辑器打开方式版本管理.env不入库.env.defaults承载默认值生效时机修改.env后重启yarn rw dev才会生效。围绕本文主题你还可以在仓库中进一步阅读环境变量文档当前版本文档、redwood.toml 配置参考以及环境变量加载的完整实现 packages/cli-helpers/src/lib/loadEnvFiles.ts 与 Web 端注入实现 packages/vite/src/lib/envVarDefinitions.ts。【免费下载链接】redwoodRedwoodGraphQL项目地址: https://gitcode.com/gh_mirrors/re/redwood创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考