企业官网建设流程全解析

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 上托管站点时，你需要为两类环境分别配置变量：

1. Production Builds 与 Pull Request Builds（生产构建与拉取请求构建）——即常规的gatsby build产出，以及每个 PR 触发的预览构建，对应Build variables；
2. CMS Previews（CMS 预览）——内容编辑者在 CMS 后台点击「预览」时触发的构建，对应Preview variables。

两者通过仪表盘中的两组独立输入框区分，互不混淆。本指南假定你的站点已在 Gatsby Cloud 中创建完成。

在仪表盘中设置环境变量

环境变量的配置入口位于站点仪表盘：点击Site Settings > General > Environment Variables打开环境变量面板。

操作步骤：

1. 点击Edit Variables（编辑变量）图标，进入添加/更新模式；
2. 每个变量有两栏：第一栏是变量name（名称），第二栏是变量value（值）；
3. 按变量作用域归类填写：
   • Build variables：作用于 Production Builds 与 Pull Request Builds；
   • Preview variables：作用于 CMS Previews；
4. 两类变量都编辑完成后，点击Save保存。

注意：编辑环境变量会触发一次新的站点构建——这是由构建系统在启动时读取环境快照所决定的，修改后需要重新构建才能让新值生效。

批量复制 / 批量添加变量

当变量较多时，Gatsby Cloud 提供了批量操作以提升效率：

• Bulk Copy Variables（批量复制）：点击 Edit Variables 后，再点击 Bulk Copy Variables 按钮，即可把当前 Build 或 Preview 环境下的全部变量一次性复制出来（例如复制到其他站点）；
• Bulk Add Variables（批量添加）：点击 Bulk Add Variables 按钮，按name=value的格式逐行输入，每行一个变量，即可一次性添加多个变量。

批量添加遵循一个明确的合并语义：新增变量不会覆盖已存在的同名变量，而是追加到当前列表末尾。因此，如果你希望用批量方式更新某个变量，需要先批量添加新值，再手动删除旧的变量条目，从而实现「覆盖」效果。

在源码中访问环境变量

在 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.ts（gatsby-node.ts）中，Gatsby Functions 的编译逻辑采用了与 webpack 完全一致的.env解析策略（代码注释明确写着 "Logic is shared with webpack.config.js"），保证gatsby-*.js文件与 Functions 能拿到同样的环境变量。

保留变量：哪些不可覆盖

为了不破坏 Gatsby 自身的运行机制，以下变量被框架锁定，不允许被.env文件或环境覆盖（webpack.config.js）：

• NODE_ENV
• PUBLIC_DIR
• BUILD_STAGE（构建阶段标识，如build-javascript、develop）

若你的.env或 Cloud 变量中出现了同名键，框架会强制使用内部计算值，这是需要留意的一个坑。

本地开发与 Cloud 的配合：.env文件约定

在本地开发中，Gatsby 遵循同样的加载约定（详见 本地开发环境变量指南）：

• 开发模式下读取.env.development；
• 构建（生产）时读取.env.production。

一个典型的.env.development文件：

GATSBY_API_URL=https://dev.example.com/api API_KEY=927349872349798

如果你在gatsby-config.js顶部调用dotenv手动加载，可以控制文件名甚至自定义多环境（Staging、Test 等），例如通过STAGING=true 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），否则前端代码中取到的是undefined（environment-variables.md）。这与上文 webpack 注入逻辑中key.match(/^GATSBY_/)的过滤规则完全对应，属于同一条机制的两种表述。

实践建议与注意事项汇总

1. 按环境隔离密钥：Build variables 与 Preview variables 分开管理，Preview 环境可单独配置指向 staging CMS 的密钥，避免预览构建误用生产凭据；
2. 改动即重建：编辑任何环境变量都会触发新构建，请在工作窗口外执行批量修改，减少不必要的构建排队；
3. 批量更新采用「追加 + 删除」策略：Bulk Add 不会覆盖同名变量，需要先加新值再删旧值；
4. 不要硬编码密钥：所有敏感值一律走仪表盘或.env文件，配合.gitignore防止泄密；
5. 留意保留变量：不要试图覆盖NODE_ENV、PUBLIC_DIR等框架内部变量。

相关文档延伸

• Gatsby Cloud 环境变量参考：Cloud 平台特有的内置变量说明；
• CMS 预览机制：理解 Preview variables 的触发链路；
• Production Builds 与 Pull Request Builds：Build variables 对应的构建类型详解；
• Monorepos 支持：Monorepo 结构下环境变量的配置方式；
• 本地开发环境变量：.env文件、GATSBY_前缀与保留变量的完整说明；
• 环境变量注入实现 与 Functions 环境变量加载：源码级验证本文所述机制。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby