Gatsby Cloud构建环境变量配置异常，无法区分预览与生产构建

核心解决方案：利用Gatsby Cloud内置变量+环境变量配置 #

方案一：推荐使用Gatsby Cloud内置环境变量配置（更可靠） #

直接在Gatsby Cloud站点后台配置环境变量，避免本地.env文件的加载冲突：

1. 进入Gatsby Cloud你的站点设置，找到Environment Variables
   • Production（生产环境）：添加GATSBY_GRAPHQL_URL（生产WordPress后端地址）、GATSBY_STRIPE_KEY等生产变量
   • Preview/PR Builds（预览环境）：添加GATSBY_GRAPHQL_URL（预发布WordPress后端地址）、对应预览环境的Stripe密钥等变量
2. 修改gatsby-config.js直接读取配置好的变量：

console.log(`** Build Type: ${process.env.IS_PRODUCTION_BRANCH ? 'Production' : 'Preview/PR'}`);
console.log("** BACKEND URL:", process.env.GATSBY_GRAPHQL_URL);
console.log("** GATSBY_STRIPE_KEY:", process.env.GATSBY_STRIPE_KEY?.substring(0, 10) || 'Not set');
console.log("** GATSBY_STRIPE_SECRET_KEY:", process.env.GATSBY_STRIPE_SECRET_KEY?.substring(0, 10) || 'Not set');

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-wordpress`,
      options: {
        url: process.env.GATSBY_GRAPHQL_URL,
        // 其他WordPress插件配置
      },
    },
    // 其他插件配置
  ],
};

此配置下，PR预览构建会自动调用预览环境变量，master分支的生产构建自动使用生产变量，无需手动处理.env文件。

方案二：基于本地.env文件的配置（适合需保留本地文件场景） #

若必须依赖本地.env文件，需明确区分Gatsby Cloud的构建类型，避免自动加载冲突：

1. 新增.env.staging文件存放预发布环境变量
2. 修改gatsby-config.js：

// 清除可能已自动加载的变量，避免冲突
delete process.env.GATSBY_GRAPHQL_URL;
delete process.env.GATSBY_STRIPE_KEY;
delete process.env.GATSBY_STRIPE_SECRET_KEY;

let envPath;
if (process.env.IS_PRODUCTION_BRANCH) {
  envPath = '.env.production';
  console.log('ENV: Loading .env.production');
} else if (process.env.IS_PR_BUILD) {
  envPath = '.env.staging';
  console.log('ENV: Loading .env.staging');
} else {
  envPath = '.env.development';
  console.log('ENV: Loading .env.development');
}

require("dotenv").config({ path: envPath });

console.log(`** Build Env: ${envPath}`);
console.log("** BACKEND URL:", process.env.GATSBY_GRAPHQL_URL);
console.log("** GATSBY_STRIPE_KEY:", process.env.GATSBY_STRIPE_KEY.substring(0, 10));
console.log("** GATSBY_STRIPE_SECRET_KEY:", process.env.GATSBY_STRIPE_SECRET_KEY.substring(0, 10));

module.exports = {
  // 你的Gatsby配置
};

注意：需确保.env文件已提交至GitHub，或在Gatsby Cloud后台禁用自动加载.env文件的默认行为。

问题根源排查 #

1. GATSBY_IS_PREVIEW始终为true：该变量在PR预览、master分支预览构建中都会被设为true，无法区分生产构建与PR构建，应改用IS_PRODUCTION_BRANCH（生产构建为true）和IS_PR_BUILD（PR构建为true）。
2. PR构建加载.env.production：Gatsby Cloud默认会在生产模式构建中自动加载.env.production，若PR构建误触发生产模式检测，或dotenv加载顺序冲突，就会出现此问题。通过明确判断IS_PR_BUILD加载对应.env.staging可解决。

内容的提问来源于stack exchange，提问作者Michael Christopher Martire