VSCode 1.77+原生支持OpenAPI 3.x预览，无需插件；需满足：文件为.yaml/.yml/.json后缀、以openapi: 3.0.3或3.1.0开头、语言模式设为OpenAPI Specification，并在settings.json中配置v3.1 Schema校验。
VSCode 1.77+ 已原生支持 OpenAPI 3.x 实时预览，不需要装任何 Swagger 插件——装了反而容易冲突或报错。
确认文件和环境是否满足基本条件
预览功能不是“点了就出”，它会先校验文件是否符合 OpenAPI 的最低准入标准：
-
openapi.yaml或openapi.yml文件必须以openapi: 3.0.3或openapi: 3.1.0开头（swagger: "2.0"不认） - 后缀只能是
.yaml、.yml或.json（.swagger不支持） - 右下角状态栏必须显示
YAML (OpenAPI)或OpenAPI Specification；如果只显示YAML，右键文件 →Change Language Mode→ 手动选OpenAPI Specification - VSCode 版本低于 1.77？升级是最直接的解法，旧版本压根没这个按钮
手动绑定 OpenAPI Schema 才有语法提示和校验
Red Hat YAML 插件不会自动拉取官方 Schema，不配就只有基础高亮，没有 $ref 跳转、字段补全、enum 校验这些关键能力：
打开 settings.json（设置 → 右上角“打开设置(JSON)”），加这段：
"yaml.schemas": {
"https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.json": ["*.yaml", "*.yml"]
}
- 如果项目只用一个
openapi.yaml，把["*.yaml", "*.yml"]换成["openapi.yaml"]，避免误校验其他 YAML 文件 - 改完保存，**重新打开文件**，再看问题面板（
Cmd+Shift+M）有没有红色波浪线 - 别用本地缓存的 schema.json 路径——VSCode 只认远程 URL 或绝对路径，相对路径无效
$ref 引用本地文件总报 file not found？
这不是路径写错了，是 VSCode 默认不把 .yaml 当 OpenAPI 文档处理：
- 被引用的文件（比如
./components/schemas/User.yaml）也必须以openapi: 3.1.0开头（哪怕只是空行 + 这一行） - 路径必须用正斜杠
/，Windows 上写.\components\...会失败 - 确保文件真实存在，且没有隐藏后缀（比如实际是
User.yaml.txt） -
$ref不支持https://地址，本地开发别试，必卡住或 CORS 报错
点 Preview 按钮没反应或显示 “No OpenAPI definition found”
这不是插件坏了，是文档结构没过第一道关。VSCode 预览器比人还较真：
- 检查
info和paths字段是否存在（哪怕内容是空对象{}也得有） - 缩进混用了 Tab 和空格？YAML 解析直接崩，建议在项目根目录加
.editorconfig强制indent_style = space - 禁用保存时自动重排 key：
"yaml.format.enable": false，否则多人编辑后 Git diff 全乱 - 想验证结构是否合法，终端跑一句：
swagger-cli validate openapi.yaml，提前卡住非法提交
真正麻烦的从来不是“怎么点开预览”，而是 $ref 文件的格式一致性、info 字段的强制存在、以及团队里没人记得要给每个被引用的 YAML 加 openapi: 3.1.0 ——这些地方一漏，预览就断，而且错误提示还不明显。
