如何获取GitLab环境变量供gatsby-*.js文件使用

1. GitLab项目设置里存储的CI/CD环境变量，仅在流水线作业实际启动运行时才会注入到执行环境，本地编辑.gitlab-ci.yml的阶段、本地开发环境未手动导出变量时，完全无法读取到这些值，不存在本地编辑配置就能直接访问GitLab私密变量的可能。
2. 你之前读取失败和Gatsby插件无关，不需要额外安装任何环境变量相关插件，核心问题是混淆了Gatsby环境变量的作用域规则，以及CI变量的透传逻辑。

• 第一步：修正GitLab侧变量配置
  • 进入项目「设置 > CI/CD > 变量」页面，确认存储私密API令牌的变量类型选择为Variable，不要选File类型（File类型会把变量值写入临时文件，环境变量本身存储的是临时文件路径，直接读取会拿到路径而非令牌值）
  • 如果开启了「受保护变量」开关，确认执行构建的分支/标签属于受保护范围，否则非受保护分支的作业拿不到该变量值
  • 不要给私密API令牌加GATSBY_前缀：所有带GATSBY_前缀的环境变量会被Gatsby明文注入到前端客户端静态包中，会直接造成密钥泄露，这类前缀仅适用于需要在浏览器侧运行的非敏感配置。
• 第二步：按Gatsby文件类型匹配读取方式
  • 对于gatsby-config.js、gatsby-node.js、gatsby-ssr.js这类运行在Node.js构建上下文的文件，直接通过process.env.你在GitLab配置的变量名读取即可，不需要任何前缀，比如你在GitLab存的变量叫PRIVATE_API_TOKEN，代码里直接写process.env.PRIVATE_API_TOKEN就能取到值
  • 仅当变量是需要在页面组件、客户端交互逻辑中使用的非敏感值（比如站点公共标识、统计ID这类），才需要加GATSBY_前缀命名
• 第三步：修正CI脚本的变量透传逻辑
  不要做TOKEN: "${GATSBY_TOKEN}"这类冗余的变量映射，CI作业启动后，所有配置在GitLab的变量会自动注入到当前shell环境，Node子进程执行Gatsby构建时会自动继承这些环境变量，参考可直接用的脚本配置：

  build:
    stage: build
    image: node:18-alpine # 替换为你项目实际使用的Node版本
    script:
      # 先做变量校验，避免后续构建才发现变量缺失，不要直接echo变量值避免泄露
      - echo "当前检测到API令牌长度：${#PRIVATE_API_TOKEN}"
      # 安装依赖
      - npm ci
      # 直接执行构建，不需要额外传参
      - npm run build
  

  如果你是在CI作业里用Docker容器跑Gatsby构建，记得在docker run命令中加上--env PRIVATE_API_TOKEN参数，把CI环境的变量透传入容器，否则容器内部无法读取宿主机的环境变量。

• 环境变量名大小写完全敏感，代码里写的变量名必须和GitLab中存储的变量名完全一致，差一个字符都会读取到undefined
• 如果仍然读不到，可以在gatsby-config.js最顶部加一行调试代码：console.log(process.env.PRIVATE_API_TOKEN ? "令牌存在" : "令牌缺失")，看CI构建日志的输出判断变量是否成功传入Gatsby进程，不要直接打印变量值避免日志泄露密钥
• 本地开发时如果需要调试相关逻辑，直接在终端执行export PRIVATE_API_TOKEN=你的本地测试令牌再启动gatsby develop即可，不需要创建.env文件，符合你不使用.env的需求
• 之前你给私密变量加GATSBY_前缀的操作存在安全风险，务必去掉前缀，避免构建后密钥被打包进前端静态资源被公开访问。

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