GitLab CI多行命令调试：如何查看完整执行脚本？

DevOps 小满

2026-7-11

解决GitLab CI折叠脚本无法完整打印的调试方法

针对你遇到的GitLab CI中锚点引用的多行脚本出错时日志被截断、无法查看完整执行内容的问题，分享几个高效的调试方法：

提前打印完整脚本内容
在执行锚点脚本前，先把要运行的命令打印出来，避免日志截断后看不到执行内容。可以通过bash的Here Document来输出锚点内容：
```
.common-script: &common-script |
   command 1
   command 2
   command x

job:
  script:
      - cd somewhere
      - # 打印即将执行的完整脚本
      - echo "===== 待执行脚本内容 ====="
      - cat << 'EOF'
        *common-script
        EOF
      - *common-script 
```
这样在日志里会先输出完整的脚本内容，即使后续命令执行出错被截断，也能提前看到所有要运行的命令。
开启命令追踪模式
在锚点脚本中加入set -x，让bash打印每一条实际执行的命令（包括参数），这样每一步的执行细节都会被记录：
```
.common-script: &common-script |
   set -x
   command 1
   command 2
   command x
   set +x # 执行完后关闭追踪
```
开启后，日志会逐条输出执行的命令，方便定位哪一步出错，以及命令的实际执行参数。
启用GitLab CI调试追踪
通过设置CI_DEBUG_TRACE环境变量，让GitLab输出更详细的CI执行日志，包括脚本的展开过程、环境变量等：
```
job:
  variables:
    CI_DEBUG_TRACE: "true"
  script:
      - cd somewhere
      - *common-script 
```
注意：开启后日志量会大幅增加，调试完成后建议关闭，避免占用过多存储。
调整日志截断限制
进入项目的「Settings > CI/CD > Pipelines」页面，找到「Log limits」选项，调整最大日志文件大小和行数上限，减少日志被截断的概率。不过这个方法只能缓解，无法完全避免超长日志的截断问题。