GitLab CI中dotenv使用问题：Gatsby构建环境变量无法读取排查

问题背景 #

在GitLab CI执行Gatsby构建时，已通过echo生成内容正确的.env.production文件，但Gatsby的gatsby-config.ts读取process.env.SITE_URL时失败，报错：

error The site's gatsby-config failed validation:
"siteMetadata.siteUrl" must be a valid uri

说明process.env中未正确加载该变量，以下是具体排查步骤：

1. 确认NODE_ENV环境变量是否为production #

你的dotenv加载逻辑依赖process.env.NODE_ENV来指定.env文件路径：path: .env.${process.env.NODE_ENV}，但GitLab CI默认不会自动设置NODE_ENV为production。需要在构建命令中明确指定：

NODE_ENV=production ./node_modules/.bin/gatsby build --prefix-paths

若NODE_ENV不是production，dotenv会尝试加载错误的.env文件（如.env.development），导致无法读取目标变量。

2. 验证dotenv的加载时机与结果 #

在gatsby-config.ts中添加日志，确认dotenv的加载状态：

import type { GatsbyConfig } from "gatsby";

// 新增日志：打印当前环境与dotenv加载结果
console.log("当前NODE_ENV:", process.env.NODE_ENV);
const result = require("dotenv").config({
  path: `.env.${process.env.NODE_ENV}`,
});

if (result.error) {
  console.error("dotenv加载错误:", result.error);
} else {
  console.log("dotenv加载的变量:", result.parsed);
}

const config: GatsbyConfig = {
  siteMetadata: {
    siteUrl: process.env.SITE_URL,
    // ...其他配置
  },
  // ...其他配置
};

export default config;

查看GitLab CI日志中的相关输出，确认NODE_ENV值和加载的变量列表是否符合预期。

3. 检查.env文件的路径正确性 #

GitLab CI的工作目录可能与本地不同，需确保.env.production存在于项目根目录。可在构建前添加命令验证：

- pwd
- ls -la .env.*

确认文件路径和存在性无误。

4. 绕过.env文件，直接注入环境变量 #

跳过.env文件，直接在CI脚本中将SITE_URL注入到process.env：

- SITE_URL=$SITE_URL NODE_ENV=production ./node_modules/.bin/gatsby build --prefix-paths

若此方式能正常构建，说明问题出在dotenv加载环节，而非变量本身。

5. 校验SITE_URL的格式与类型 #

Gatsby的GatsbyConfig类型对siteUrl格式要求严格，若变量存在但格式不符合URI标准（如末尾多空格、含非法字符），也会触发报错。在gatsby-config.ts中添加日志验证：

console.log("SITE_URL的值:", process.env.SITE_URL);
console.log("SITE_URL的类型:", typeof process.env.SITE_URL);

确认变量为有效字符串且格式合规。

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