Gatsby Cloud 环境变量管理完全指南配置 Build 与 CMS Preview 两套环境【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby导读环境变量Environment Variables是让同一个 Gatsby 站点在不同环境下使用不同配置的标准手段最常见的用途是把 API Token、密钥等敏感信息注入应用避免在源码中硬编码。本文以 Gatsby Cloud 为对象完整讲解如何通过站点仪表盘为 Production Builds / Pull Request Builds 与 CMS Previews 两类环境分别设置环境变量、如何批量添加/复制变量以及如何在源码中通过process.env读取它们同时结合当前仓库中 Gatsby 开源框架的 webpack 注入与.env文件解析实现webpack.config.js、functions/gatsby-node.ts从机制层面解释这些变量在构建与浏览器端的真实去向。读完本文你将能够独立完成 Gatsby Cloud 站点的环境变量配置与排障。为什么需要环境变量先理解两类环境环境变量允许你为 Gatsby 站点提供「环境特定」的配置。一个典型场景是把 Contentful、Sanity 等 CMS 的 API Token 通过环境变量注入构建过程源代码中不再出现任何明文密钥管理环境变量官方指南。在 Gatsby Cloud 上托管站点时你需要为两类环境分别配置变量Production Builds 与 Pull Request Builds生产构建与拉取请求构建——即常规的gatsby build产出以及每个 PR 触发的预览构建对应Build variablesCMS PreviewsCMS 预览——内容编辑者在 CMS 后台点击「预览」时触发的构建对应Preview variables。两者通过仪表盘中的两组独立输入框区分互不混淆。本指南假定你的站点已在 Gatsby Cloud 中创建完成。在仪表盘中设置环境变量环境变量的配置入口位于站点仪表盘点击Site Settings General Environment Variables打开环境变量面板。操作步骤点击Edit Variables编辑变量图标进入添加/更新模式每个变量有两栏第一栏是变量name名称第二栏是变量value值按变量作用域归类填写Build variables作用于 Production Builds 与 Pull Request BuildsPreview variables作用于 CMS Previews两类变量都编辑完成后点击Save保存。注意编辑环境变量会触发一次新的站点构建——这是由构建系统在启动时读取环境快照所决定的修改后需要重新构建才能让新值生效。批量复制 / 批量添加变量当变量较多时Gatsby Cloud 提供了批量操作以提升效率Bulk Copy Variables批量复制点击 Edit Variables 后再点击 Bulk Copy Variables 按钮即可把当前 Build 或 Preview 环境下的全部变量一次性复制出来例如复制到其他站点Bulk Add Variables批量添加点击 Bulk Add Variables 按钮按namevalue的格式逐行输入每行一个变量即可一次性添加多个变量。批量添加遵循一个明确的合并语义新增变量不会覆盖已存在的同名变量而是追加到当前列表末尾。因此如果你希望用批量方式更新某个变量需要先批量添加新值再手动删除旧的变量条目从而实现「覆盖」效果。在源码中访问环境变量在 Gatsby Cloud 中配置好的变量会作为进程环境变量注入构建与运行时。在源码中通过标准的process.env.variable name语法访问。官方文档给出的示例managing-environment-variables.md展示了如何组装一个 Contentful 配置对象const contentfulConfig { spaceId: process.env.CONTENTFUL_SPACE_ID, accessToken: process.env.CONTENTFUL_ACCESS_TOKEN, } if (process.env.CONTENTFUL_HOST) { contentfulConfig.host process.env.CONTENTFUL_HOST }这里CONTENTFUL_SPACE_ID、CONTENTFUL_ACCESS_TOKEN、CONTENTFUL_HOST都是在仪表盘中定义的 Build variables或 Preview variables。将该对象用于gatsby-config.js中的gatsby-source-contentful插件即可该插件的源码位于 packages/gatsby-source-contentful。机制剖析变量如何从 Cloud 进入你的构建要真正用好环境变量值得理解 Gatsby 开源框架侧的处理管线——这也是 Gatsby Cloud 构建流程的底层基础。webpack 侧的注入processEnv与 DefinePlugin在 packages/gatsby/src/utils/webpack.config.js 中processEnv函数负责为每个构建阶段生成可供前端代码使用的process.env.*常量它先确定nodeEnv来自process.env.NODE_ENV缺省为development与configEnv由GATSBY_ACTIVE_ENV覆盖缺省同nodeEnv然后通过dotenv.parse读取项目根目录下的./.env.${configEnv}文件webpack.config.js对build-html/develop-html阶段目标为node其余阶段目标为web当目标是web时只有键名匹配GATSBY_前缀的变量才会被注入其余来自process.env的变量只保留给 Node 侧webpack.config.js最终把这些键值交给 webpack 的DefinePlugin做编译期替换形成process.env.${key}的字面量常量。这正是「变量在 JavaScript 编译/构建时被固化」这一行为的实现来源也解释了为何修改变量后必须重新构建。在packages/gatsby/src/internal-plugins/functions/gatsby-node.tsgatsby-node.ts中Gatsby Functions 的编译逻辑采用了与 webpack 完全一致的.env解析策略代码注释明确写着 Logic is shared with webpack.config.js保证gatsby-*.js文件与 Functions 能拿到同样的环境变量。保留变量哪些不可覆盖为了不破坏 Gatsby 自身的运行机制以下变量被框架锁定不允许被.env文件或环境覆盖webpack.config.jsNODE_ENVPUBLIC_DIRBUILD_STAGE构建阶段标识如build-javascript、develop若你的.env或 Cloud 变量中出现了同名键框架会强制使用内部计算值这是需要留意的一个坑。本地开发与 Cloud 的配合.env文件约定在本地开发中Gatsby 遵循同样的加载约定详见 本地开发环境变量指南开发模式下读取.env.development构建生产时读取.env.production。一个典型的.env.development文件GATSBY_API_URLhttps://dev.example.com/api API_KEY927349872349798如果你在gatsby-config.js顶部调用dotenv手动加载可以控制文件名甚至自定义多环境Staging、Test 等例如通过STAGINGtrue gatsby build配合条件式dotenv配置实现额外环境。安全约定.env*文件通常包含密钥不应提交进 Git——建议把.env.*加入.gitignore然后在 Gatsby Cloud 的 Site Settings 中手动配置对应变量这正是本文介绍的仪表盘操作本地则由.env文件承担。浏览器端的可见性边界默认情况下环境变量只在 Node.js 代码gatsby-config.js、gatsby-node.js、Functions中可用不会暴露给浏览器——因为某些变量需要保密。若某个变量需要在前端组件中读取其名称必须以GATSBY_开头如GATSBY_API_URL否则前端代码中取到的是undefinedenvironment-variables.md。这与上文 webpack 注入逻辑中key.match(/^GATSBY_/)的过滤规则完全对应属于同一条机制的两种表述。实践建议与注意事项汇总按环境隔离密钥Build variables 与 Preview variables 分开管理Preview 环境可单独配置指向 staging CMS 的密钥避免预览构建误用生产凭据改动即重建编辑任何环境变量都会触发新构建请在工作窗口外执行批量修改减少不必要的构建排队批量更新采用「追加 删除」策略Bulk Add 不会覆盖同名变量需要先加新值再删旧值不要硬编码密钥所有敏感值一律走仪表盘或.env文件配合.gitignore防止泄密留意保留变量不要试图覆盖NODE_ENV、PUBLIC_DIR等框架内部变量。相关文档延伸Gatsby Cloud 环境变量参考Cloud 平台特有的内置变量说明CMS 预览机制理解 Preview variables 的触发链路Production Builds 与 Pull Request BuildsBuild variables 对应的构建类型详解Monorepos 支持Monorepo 结构下环境变量的配置方式本地开发环境变量.env文件、GATSBY_前缀与保留变量的完整说明环境变量注入实现 与 Functions 环境变量加载源码级验证本文所述机制。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考