必须安装Jenkins Pipeline Linter Connector，因Groovy扩展仅支持标准语法，无法识别agent、stage、steps等Jenkins DSL关键字；需配置正确linter URL并手动关联Jenkinsfile为Groovy类型。
必须装 Jenkins Pipeline Linter Connector，光靠 Groovy 扩展无法识别 pipeline、stage、steps 这些 DSL 关键字——它们不是 Groovy 语法，而是 Jenkins 自己注入的运行时结构。
为什么 Groovy Language Support 对 Jenkinsfile 无效
VSCode 的 Groovy Language Support 扩展只认标准 Groovy 语法：比如 def、class、if、for。但 Jenkinsfile 里大量出现的 agent、environment、sh、script 都是 Jenkins Pipeline DSL 动态注册的闭包参数或方法名，Groovy 语言服务器根本不知道它们存在。
常见错误现象：
- 输入
st按Tab不提示stage -
pipeline {后面敲ag不补全agent - 拼错
stages写成stagez，编辑器零报错
这不是扩展没装好，是它本来就不该管这事。
配置 jenkins.pipeline.linter.url 必须指向 /pipeline-model-converter/validate
这个 URL 是 Jenkins 实例提供的校验端点，不是首页地址，也不是 Jenkins 主域名。填错就等于“断联”，插件会静默失效，连红波浪线都不会出。
正确做法：
- 确认 Jenkins 已安装
Pipeline Utility Steps插件（必要依赖） - 访问
http://your-jenkins-url/pipeline-model-converter/validate，能返回{"status":"ok"}或 405 方法不支持（说明端点存在）才算通 - 在 VSCode 设置中搜索
jenkins.pipeline.linter.url，值设为完整 URL，结尾必须带/validate - 如果 Jenkins 启用了 CSRF 保护，需在设置中额外配置
jenkins.pipeline.linter.csrf.enabled为true，并确保登录态有效
别用 http://localhost:8080 这种裸地址——它只会触发 404，且插件不报错，只默默跳过校验。
文件关联必须显式设为 Groovy，不能靠后缀猜
VSCode 默认不把无扩展名的 Jenkinsfile 当作 Groovy 处理，也不会自动加载 Jenkins DSL 支持。即使装了所有插件，右下角显示 “Plain Text” 就代表整个高亮和补全链已断裂。
必须手动配置文件关联：
- 打开
settings.json（Cmd+, → 右上角点击“打开设置（JSON）”） - 添加：
"files.associations": { "Jenkinsfile": "groovy", "*.gradle": "groovy" } - 保存后，重新打开 Jenkinsfile —— 右下角应显示 “Groovy”，不是 “Plain Text” 或 “Jenkinsfile”
注意：Jenkinsfile Support (Groovy) 这类扩展名字有误导性，它不改文件类型，只是加了些 snippets；真正起作用的是上面这行 JSON 配置。
调试 Jenkinsfile 逻辑前，先验证 linter 是否真在工作
很多人卡在“写了 sh 'ls' 却没提示”，其实是 linter 根本没跑起来。最简单的验证方式：
- 在 Jenkinsfile 中故意写错：比如
stages { stage('build') { steps { sh 'exi' } } }（exi不是合法命令） - 保存文件，看右下角状态栏是否出现
Jenkins Linter: Valid Jenkinsfile或具体错误行号 - 若无反应，打开 VSCode 输出面板（Ctrl+Shift+U），选择 “Jenkins Pipeline Linter Connector”，看是否有
HTTP 401或ENOTFOUND日志
最容易被忽略的一点：Jenkins 实例若启用了反向代理（如 Nginx），/pipeline-model-converter/validate 端点可能被重写或拦截，此时需检查代理配置是否透传了 POST 请求与 header。
