Gatsby无法设置环境变量问题求助

我之前在配置Gatsby多环境变量时也踩过几乎一模一样的坑，咱们从几个关键环节排查修复：

1. 确保环境变量跨系统正常传递 #

你的部署脚本里用了DEPLOY_ENV=staging这种写法，这在Mac/Linux等Unix-like系统下没问题，但在Windows系统中会直接失效。解决办法是用cross-env包统一跨系统的环境变量设置逻辑：

首先安装依赖：

npm install cross-env --save-dev

然后修改package.json里的部署脚本：

"deploy:staging": "cross-env DEPLOY_ENV=staging gatsby build --prefix-paths && s3-deploy ..."

2. 让环境变量同时在Node和浏览器环境生效 #

你在gatsby-config.js里用dotenv加载了变量，但这些变量默认只在Node环境（比如gatsby-config、gatsby-node.js这类构建脚本）可用，像src/html.js这种浏览器端的文件是拿不到的。这里给你两种可行的传递方案：

方案A：通过siteMetadata传递 #

在gatsby-config.js里把需要的变量注入到站点元数据中：

require("dotenv").config({ path: `.env.${process.env.DEPLOY_ENV}` });

module.exports = {
  siteMetadata: {
    assetHost: process.env.ASSET_HOST,
  },
  // 其他原有配置...
};

然后在src/html.js里通过静态查询获取该变量：

import { useStaticQuery, graphql } from "gatsby";

const Html = ({ ...props }) => {
  const siteData = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          assetHost
        }
      }
    }
  `);
  
  return (
    // 原有html结构...
    <script src={`//${siteData.site.siteMetadata.assetHost}/app.js`}></script>
    // 原有html结构...
  );
};

方案B：用Gatsby插件直接暴露给浏览器 #

安装专门的环境变量插件：

npm install gatsby-plugin-env-variables --save-dev

然后在gatsby-config.js里配置允许暴露给浏览器的变量列表：

require("dotenv").config({ path: `.env.${process.env.DEPLOY_ENV}` });

module.exports = {
  // 其他原有配置...
  plugins: [
    // 其他原有插件...
    {
      resolve: `gatsby-plugin-env-variables`,
      options: {
        allowList: ["ASSET_HOST"]
      }
    }
  ]
};

配置完成后，你就能在src/html.js里直接使用process.env.ASSET_HOST了。

3. 验证dotenv的加载路径是否正确 #

有时候看似路径正确，但实际当前工作目录不是项目根目录，导致dotenv找不到对应的.env文件。可以在gatsby-config.js里打印完整路径确认：

const path = require('path');
const envFilePath = path.resolve(__dirname, `.env.${process.env.DEPLOY_ENV}`);
console.log(`当前加载的环境变量文件路径：${envFilePath}`);
require("dotenv").config({ path: envFilePath });

如果打印的路径不对，改成绝对路径就能解决问题。

4. 确认.env文件的格式正确 #

检查你的.env.staging等文件，确保变量格式是ASSET_HOST=your-host-domain.com——不要加引号，也不要在等号前后加多余空格，否则dotenv无法正确解析。

按照上面的步骤调整后，应该就能正常加载对应环境的变量了。

内容的提问来源于stack exchange，提问作者jordan