VSCode 的 Puppet 扩展默认不集成语法检查功能，必须手动配置 puppet-lint 路径并启用相关开关才能实现报错、高亮和修复；仅安装扩展只能提供语法高亮等基础功能。
VSCode 对 Puppet 脚本默认不提供语法检查，必须手动接入 puppet-lint 才能报错、高亮和修复——装了 Puppet 扩展但没配 puppet-lint，等于只开了语法高亮的灯，关着错误检测的门。
为什么 Puppet 扩展装了却没报错？
VSCode 的 Puppet 扩展（如 Puppet by jfryman）只负责语法高亮、代码折叠和基础补全，它本身不带任何 lint 引擎。所谓“语法检查”实际是调用外部命令 puppet-lint 完成的，而该工具默认不会随扩展自动安装或自动发现。
- 常见现象：
.pp文件里写错资源类型（比如把file {写成files {），VSCode 无任何波浪线或提示 - 根本原因：VSCode 没找到
puppet-lint可执行文件，或找到了但没启用检查开关 - 验证方式：终端运行
puppet-lint --version，若报command not found，说明 Ruby 环境或 gem 没装好
如何让 puppet-lint 被 VSCode 正确调用？
关键不是“装没装”，而是“VSCode 能不能在当前工作区里准确执行它”。路径配置错一个字符，检查就静默失效。
- 先确保系统级可用：运行
gem install puppet-lint（macOS/Linux）或choco install puppet-lint（Windows + Chocolatey） - 如果项目用 Bundler，应在
Gemfile中添加gem "puppet-lint"，再运行bundle install - VSCode 设置中搜索
puppet.lint.puppetLintPath，填入绝对路径（推荐）：
macOS/Linux：/usr/local/bin/puppet-lint或~/.gem/ruby/*/bin/puppet-lint
Windows：C:\Ruby31-x64\bin\puppet-lint.bat（按你实际 Ruby 安装路径调整） - 务必启用开关：
"puppet.lint.enabled": true，否则路径对了也白搭
格式化和检查行为不一致？注意这两个配置项
puppet-lint 默认只做检查，不修改代码；而 VSCode 的“格式化”功能（editor.formatOnSave）需要额外桥接。二者逻辑分离，容易误以为“开了格式化就等于开了检查”。
- 检查触发条件：
puppet.lint.enabled+puppet.lint.onSave（默认 true） - 格式化触发条件：
editor.formatOnSave+puppet.format.enable（部分 Puppet 扩展支持，非所有版本都含） - 若想保存即修复（如自动补空格、换行），需确认扩展支持
--fix参数，并在puppet.lint.puppetLintArgs中加入["--fix"] - 注意冲突：
puppet-lint --fix不处理所有风格问题（例如缩进宽度需靠--indent-size=2单独控制）
常见静默失败场景与排查顺序
最麻烦的不是报错，而是“什么也不发生”。以下顺序排查效率最高：
- 打开命令面板（
Ctrl+Shift+P），执行Puppet: Show Output，看输出通道里有没有puppet-lint启动日志或ENOENT错误 - 检查当前工作区是否在 Puppet 模块根目录（即含
metadata.json和manifests/的目录），puppet-lint会据此判断模块上下文 - 确认
.pp文件右下角显示的是Puppet语法（不是Plain Text或HTML），否则扩展根本不响应 - 禁用其他可能干扰的扩展（如某些通用 YAML 或 Ruby 插件），避免语言服务器抢注
.pp关联
真正卡住的地方，往往不是 Ruby 版本或 gem 权限，而是 VSCode 当前打开的文件夹没被识别为 Puppet 工作区，或者 puppet-lint 路径指向了一个旧版本、已卸载的 Ruby 实例——这类路径问题，在多版本 Ruby 共存（rbenv/rvm）环境下尤其隐蔽。
