必须安装jenkins pipeline linter connector插件，正确配置jenkins.pipeline.linter.connector.url指向/pipeline-model-converter/validate端点，并将jenkinsfile文件显式关联为groovy语言模式，三者缺一不可。
装对插件只是第一步，真正起作用的是 jenkins.pipeline.linter.url 配置和文件语言模式。光装 Groovy 或 Jenkins Pipeline Support 扩展，stage、steps 这些关键字依然不会补全、也不会报错——因为它们根本不是 Groovy 语法，而是 Jenkins 运行时注入的 DSL。
必须装 Jenkins Pipeline Linter Connector（不是“Support”）
这是唯一能触发真实语法校验的插件。它不提供高亮或补全，但负责把当前 Jenkinsfile 发送到 Jenkins 实例的 /pipeline-model-converter/validate 端点，并把返回的错误/警告渲染成编辑器里的红波浪线。
-
Jenkins Pipeline Support（微软官方）只做基础高亮和代码片段，不校验逻辑 -
Groovy扩展只识别def、class、for这类标准语法，对agent、sh、script完全无感 - 别装
Jenkinsfile Support (Groovy)这类已停更或命名误导的扩展，2026 年多数已失效
配置 jenkins.pipeline.linter.url 必须精确到 /validate
填错 URL 插件会静默失效，不报错、不提示、不显示波浪线——你只会以为“校验没起作用”，实际是请求根本没发出去。
- 正确格式：
http://your-jenkins.example.com:8080/pipeline-model-converter/validate（结尾必须带/validate） - 错误示例：
http://localhost:8080、http://jenkins.example.com/、http://jenkins.example.com/jenkins→ 全部返回 404，插件不提示 - 验证是否通：在浏览器打开该 URL，应返回
{"status":"ok"}或 HTTP 405（说明端点存在，只是不允许 GET） - 如果 Jenkins 启用了 CSRF，必须同时开启
jenkins.pipeline.linter.csrf.enabled并确保 VSCode 已登录 Jenkins（或配置crumbUrl）
文件必须显式关联为 Groovy 类型
VSCode 默认把无后缀的 Jenkinsfile 当作 Plain Text，右下角显示 “Plain Text” 就代表整个链路已断裂——高亮、补全、校验全部失效。
- 点击右下角语言标识 → 选 “Configure File Association for 'Jenkinsfile'” → 设为
groovy - 或直接改
settings.json："files.associations": { "Jenkinsfile": "groovy" } - 改完后**必须重新打开**该文件，右下角应显示 “Groovy”，不是 “Jenkinsfile” 或 “Plain Text”
- 注意：仅靠
"*.groovy": "groovy"不够，Jenkinsfile没扩展名，必须单独声明
常见现象与对应排查点
看到这些表现，基本可以按顺序检查：
- 输入
st按 Tab 不出stage→ 检查是否装了Jenkins Pipeline Support，且文件语言是groovy -
pipeline { agent any; stages { stage('build') { steps { sh 'make' } } } }写错成stagez却没报错 →jenkins.pipeline.linter.url配置错误或 Jenkins 端点不通 - 右下角显示 “Jenkinsfile”（而非 “Groovy”）→ 文件关联未生效，
settings.json里没加"Jenkinsfile": "groovy" - 有波浪线但提示 “unknown method ‘sh’” → 不是语法错误，是校验服务返回了 Jenkins 解析失败结果，说明
/validate端点虽通但 Jenkins 侧解析出错（比如缺少 Pipeline Utility Steps 插件）
最关键的三个点其实是联动的：插件装对了、URL 指向真实的 /validate、文件被当成 groovy ——漏掉任一环，整个校验链就断了。很多人反复重装插件，却忽略 settings.json 里那一行 "Jenkinsfile": "groovy"，或者把 URL 复制成了 Jenkins 主页地址。
