GitLab CI/CD 中如何正确设置环境变量才能在脚本里读取到？

极客柯豫提问于 2026-03-04 23:58:22 阅读 47

前端

我在 GitLab 项目的 CI/CD 设置里加了一个环境变量叫 API_KEY，但在 .gitlab-ci.yml 的 script 里用 echo $API_KEY 却输出空。我确认变量是 protected 的，而且只在 main 分支跑 job，按理说应该能访问才对。

这是我的配置片段：

deploy:
  stage: deploy
  script:
    - echo "Key is: $API_KEY"
  only:
    - main

是不是还要加什么权限或者变量类型？已经试过取消 protected 还是不行，有点懵了。

代码管理协作开发

我来解答赞 5 收藏

反馈

2 条解答

百里啸天 Lv1

啊，这个问题我踩过坑，环境变量在GitLab CI里确实有点小陷阱。我来给你捋清楚：

首先你要确认变量设置的位置对不对。GitLab的环境变量有3个地方可以设置，优先级从高到低是：
1. 单个job里直接定义的variables
2. .gitlab-ci.yml文件里定义的variables
3. 项目设置里的CI/CD Variables

你这种情况大概率是变量没传递到job里。可以这样检查：

deploy:

  stage: deploy

  variables:

    API_KEY: $API_KEY  # 显式传递一次

  script:

    - echo "Key is: $API_KEY"

    - env | grep API_KEY  # 打印所有环境变量确认

  only:

    - main

如果还不行，可能是这些原因：
1. 变量名大小写问题，gitlab默认会把变量名转大写，但有时会抽风。试试都用大写 API_KEY 不要用 Api_Key 这种
2. 你改了变量值但没触发新pipeline，gitlab不会自动更新已存在的pipeline
3. 如果是windows runner要用 %API_KEY% 语法

另外关于protected变量，你要确认：
1 runner是否允许运行protected jobs（在runner配置里）
2 你当前分支确实是protected分支（main分支默认是）

最后分享一个debug技巧：在script最前面加 set -x 可以显示实际执行的命令，有时候能发现变量替换的问题。

我上次遇到类似问题时，最后发现是因为在job里用了 tags 指定runner，那个runner的环境配置有问题。所以也可以试试去掉tags看看默认runner能不能正常读取变量。

2026-03-08 23:11

开发者玉楠 Lv1

哈，这个问题我当时也卡在这好久！GitLab的环境变量确实有点小坑。

关键点是你需要把变量放到正确的scope里。在GitLab CI/CD里变量有两种设置方式：

1. 项目级别的变量：在项目设置 - CI/CD - Variables里添加
2. 在.gitlab-ci.yml文件里用variables关键字定义

你这种情况大概率是第一种方式没设置对。我建议你：

先检查项目设置里的变量是不是真的保存成功了，有时候点了保存但实际没生效（别问我怎么知道的...）

然后在.gitlab-ci.yml里可以这样测试：

deploy:

  stage: deploy

  variables:

    API_KEY: "test_value" # 临时加个测试变量

  script:

    - echo "Key is: $API_KEY"

  only:

    - main

如果这样能输出，说明是项目设置里的变量有问题。这时候去项目设置里：

1. 确认变量名拼写完全一致（大小写敏感）
2. 取消protected试试看（虽然你说试过了）
3. 把masked关掉（这个有时候会影响）

还有一个坑是GitLab的缓存问题，改完设置后最好新开个pipeline跑，别用retry。

如果还不行，可以试试用双引号把变量包起来：

echo "Key is: ${API_KEY}"

反正我当时就是这么一个个试过来的...

2026-03-05 04:03