必须安装 red hat yaml 插件并手动配置 gitlab ci schema 才能获得准确语法提示——插件提供字段补全、悬停说明和错误高亮，schema 关联后支持 stages、rules、image:name 等特有字段校验与建议。
用 Red Hat YAML 插件启用 .gitlab-ci.yml 语法提示
VSCode 默认不识别 .gitlab-ci.yml 的结构和关键字，直接写容易拼错 script、before_script 或漏掉 rules 的缩进层级。必须装插件才能获得字段补全、悬停提示和错误高亮。
装 YAML Language Support by Red Hat 是唯一靠谱方案——它基于 yaml-language-server，并支持通过自定义 Schema 绑定 GitLab CI 的语义规则。
- 打开 VSCode 扩展面板（
Ctrl+Shift+X），搜YAML，选 Red Hat 官方那个，点安装 - 安装完重启 VSCode，或点击“重新加载”
- 确保文件后缀是
.yml或.yaml，且文件名是.gitlab-ci.yml（VSCode 会自动识别该文件名并启用基础校验）
手动配置 GitLab CI Schema 让提示更准
仅靠插件默认行为，stages、workflow:rules、image:name 这些 GitLab 特有字段不会被校验，也不会给出合法值建议。需要手动关联官方 Schema。
编辑 VSCode 的 settings.json（Ctrl+, → 右上角“打开设置(JSON)”），在 "yaml.schemas" 下添加：
{
"https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/gitlab-ci.json": [
".gitlab-ci.yml",
"gitlab-ci.yml"
]
}
注意：gitlab-ci.json Schema 来自 SchemaStore 社区维护，覆盖了 GitLab 16.x+ 的全部关键字，包括 trigger:strategy、retry:when 等较新字段。
- 保存后，新建或重开
.gitlab-ci.yml，输入st就能自动补全stages - 输入
image:后悬停，会显示name和entrypoint字段说明 - 如果写了
script: echo hello（少了列表格式），会立刻标红并提示 “Expected sequence”
常见拼写错误与 Schema 不生效的排查点
即使装了插件、配了 Schema，仍可能没提示——多数是路径或格式细节没对上。
-
.gitlab-ci.yml文件不能放在子目录里，必须在仓库根目录；否则 VSCode 不触发绑定逻辑 - 检查文件编码是否为 UTF-8（无 BOM），BOM 会导致 Schema 加载失败
- 确认
settings.json中"yaml.schemas"是顶层字段，不是嵌套在其他配置块里 - 如果用了多根工作区（multi-root workspace），Schema 配置需放在工作区 settings 中，而非用户 settings
- 插件启用状态可在命令面板（
Ctrl+Shift+P）输入YAML: Show Schema Associations查看当前匹配结果
不用插件时的最低限度校验手段
如果因权限限制无法装插件（如公司锁死扩展市场），可用替代方式获得基础反馈：
- 在
.gitlab-ci.yml开头加注释# yaml-language-server: $schema=https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/schemas/json/gitlab-ci.json，部分旧版插件或 LSP 客户端能识别该指令 - 用命令行本地验证：
docker run --rm -i -v "$(pwd):/workspace" -w /workspace node:22-alpine sh -c "npm install -g gitlab-ci-yaml-validator && gitlab-ci-yaml-validator .gitlab-ci.yml" - GitLab 网页端提交前会做一次解析校验，但错误信息简陋（只报第几行语法错），不如 VSCode 实时提示有用
Schema 文件本身不包含执行逻辑，只负责结构描述；真正起作用的是插件背后的语言服务器——所以别指望改个 JSON 就能让 include 的远程模板也获得补全，那得靠 GitLab 自己的 LSP 支持，目前还没有。
