VSCode需asciidoctor-vscode插件配合本地asciidoctor（Ruby）或asciidoctor.js才能正常渲染AsciiDoc；仅装插件不配处理器将导致预览简陋、宏/主题/PDF导出失效，须验证asciidoctor安装、配置路径、关闭插件样式干扰、修正相对路径、安装asciidoctor-pdf及中文字体主题。
VSCode 本身不支持 AsciiDoc 渲染，必须靠 asciidoctor-vscode 插件 + 本地 asciidoctor（Ruby）或 asciidoctor.js 处理器协同工作；只装插件不配处理器，预览会降级为简陋 HTML，宏、主题、PDF 导出等功能全部失效。
确认 asciidoctor 是否已安装并可用
插件默认尝试调用系统命令 asciidoctor，不是 Ruby gem 安装的，VSCode 就找不到它。常见错误是：右键“Open Preview”后空白、报错 command 'asciidoctor.preview' not found 或预览里看不到图片/样式。
- 终端运行
asciidoctor -v，有输出说明已安装；没反应或提示 command not found，需先装 Ruby 再执行gem install asciidoctor - macOS 用户若用 Homebrew 安装 Ruby（
brew install ruby），注意检查~/.homebrew/bin是否在$PATH中，否则 VSCode 终端能运行但 GUI 启动的 VSCode 找不到命令 - Windows 用户推荐用 Ruby+DevKit 官方安装包，避免用 MSYS2 或 WSL 环境下的 Ruby，插件目前对跨子系统路径识别不稳定
- 不想装 Ruby？可设
asciidoc.use_asciidoctor_js为true，但asciidoctor.js不支持 PDF 导出、部分扩展宏（如include::相对路径在某些版本有 bug）
关闭插件自带样式干扰预览效果
默认预览套用插件内置 CSS，白底黑字、无字体控制、不加载文档中定义的 :stylesheet: 或主题，导致你写的样式全被覆盖——尤其是想用自定义主题导出 PDF 前，得先确保预览也接近终稿效果。
- 打开设置（
Cmd+,/Ctrl+,），搜索asciidoctor.use_editor_style，**取消勾选** - 同时确认
asciidoctor.preview.refreshDelay设为500（防频繁重绘卡顿） - 重启 VSCode 或重开 .adoc 文件，再右键预览，此时会读取文档头部的
:stylesdir:和:stylesheet:配置（如有） - 若仍不生效，检查文档开头是否有
:nofooter:或:notitle:等属性干扰了样式加载逻辑
图片和 include 路径在预览中不显示？
VSCode 预览对相对路径解析不如命令行严格，尤其 include:: 和 image:: 常因工作区根目录与文件实际位置不一致而 404。这不是 bug，是插件按 VSCode URI 规则解析路径的结果。
-
image::./assets/diagram.png[]在预览中失败？改用image::assets/diagram.png[]（去掉./） -
include::sections/intro.adoc[]报错？确保该文件在当前 .adoc 所在目录的sections/子目录下，且 VSCode 工作区根目录就是该 .adoc 所在父目录 - 更稳妥做法：在 VSCode 设置中配置
asciidoctor.asciidoctor_command为完整路径，例如/usr/local/bin/asciidoctor，让插件彻底走命令行流程，路径行为与终端一致 - 临时调试：终端进到 .adoc 所在目录，手动运行
asciidoctor -d article -o preview.html doc.adoc，对比输出是否正常
导出 PDF 时中文乱码或样式丢失
这是最常被忽略的环节：VSCode 预览正常 ≠ PDF 正常。PDF 渲染由 asciidoctor-pdf 独立完成，它不读 VSCode 设置，只认 Ruby 环境、字体配置和主题文件。
- 必须运行
gem install asciidoctor-pdf，且版本 ≥ 2.3.0（旧版对中文支持极差） - 下载 Noto Serif CJK 或思源宋体等 OpenType 字体，解压后在项目根目录建
fonts/文件夹，放入.otf文件 - 创建
pdf-theme.yml，明确指定font: {catalog: {Noto Serif CJK SC: {normal: fonts/NotoSerifCJKsc-Regular.otf}}}，并在文档头加:pdf-themesdir: ./和:pdf-theme: mytheme - VSCode 插件导出 PDF 功能（右键菜单 “Export to PDF”）本质是调用
asciidoctor-pdf命令，所以终端能跑通，插件才能导出成功
真正麻烦的从来不是装插件，而是让 VSCode、Ruby、asciidoctor、asciidoctor-pdf、字体、主题、路径这六者对齐同一套上下文。少一个环节，预览或导出就断在某个“看起来应该没问题”的地方。
