VSCode 正确处理 RST 需 Python 环境、docutils/sphinx 依赖、插件配置三者协同
想让 VSCode 顺畅地编写、预览和校验 RST 文档，只装一个插件是远远不够的。这里有个关键前提：Python 环境、docutils/sphinx 依赖、插件配置这三者必须协同工作，缺一不可。 很多问题都源于这三者之间的“断链”。
reStructuredText 插件装了但预览空白或报错 ModuleNotFoundError: No module named 'docutils'
这大概是新手遇到的第一个“拦路虎”。问题根源在于，插件本身只是个“外壳”，它并不自带 RST 的解析引擎。预览功能完全依赖你本地 Python 环境里是否安装了 docutils（负责基础解析）或 sphinx（提供增强渲染）。VSCode 可不会自动帮你装上这些包。
怎么解决？按这个顺序排查：
- 安装核心依赖：首先，在终端执行
pip install docutils。这是预览基础 RST 文档的绝对前提。 - 按需升级：如果你打算使用 Sphinx 主题（比如经典的
sphinx_rtd_theme），或者文档中需要用到:ref:、:toctree:这类高级指令，那就得把 Sphinx 也装上：pip install sphinx sphinx_rtd_theme。 - 统一解释器：一个常见的坑是，你装包用的 Python 环境和 VSCode 当前使用的不是同一个。按
Ctrl+Shift+P，输入Python: Select Interpreter，确保选中了你刚刚安装依赖的那个环境（例如项目虚拟环境里的venv/bin/python）。 - 检查配置路径：如果使用了 Sphinx，记得在插件设置里确认一下
restructuredtext.confPath是否指向了包含conf.py配置文件的目录。如果只是用基础功能，这个设置留空即可。
输入 .. code-block:: python 没自动补全或高亮失效
RST 的语法补全和高亮不是“开箱即用”的魔法，需要插件和编辑器语言模式正确配合才能激活。
- 确认插件已就位：首先，确保已经安装了由 lextm 维护的
reStructuredText插件，并且安装后重启过 VSCode。 - 核对语言模式：打开任意
.rst文件，看一眼编辑器右下角的状态栏。语言模式必须显示为reStructuredText。如果不是，点击它，选择Configure File Association for '.rst'，然后手动设置为reStructuredText。 - 了解触发规则：部分指令补全（比如
.. note::、.. versionadded::）需要在行首输入..后才会触发提示。而像code-block这类指令，通常需要输入完整的前缀（如.. code-block::）后再按Tab键。 - 检查编辑器设置：如果以上都做了还是没有反应，不妨检查一下 VSCode 的设置。确保
editor.suggest.showSnippets和editor.quickSuggestions这两个选项都设置为true，它们控制着代码建议的显示。
预览窗口不随编辑实时刷新，或样式丑得像纯文本
如果你觉得预览效果简陋，甚至不刷新，这很正常。因为默认的预览模式使用的是 docutils 生成的简易 HTML，几乎没有样式，也不支持主题定制。想要获得接近最终 Sphinx 构建的漂亮效果，需要主动切换到 Sphinx 预览模式。
立即学习“Python免费学习笔记（深入）”；
- 选择正确的预览命令：在
.rst文件内右键点击，选择reStructuredText: Preview with Sphinx（注意，不是那个普通的Preview选项）。 - 准备配置文件：这个命令要求你的项目工作区根目录或者
source/目录下存在conf.py文件。如果没有，可以通过运行sphinx-quickstart命令来快速初始化一个。 - 耐心与排查：首次使用 Sphinx 预览加载可能会慢一些，这是因为它需要初始化构建环境。但后续编辑保存后，通常在 1-2 秒内就会刷新。如果延迟异常高，可以检查一下
conf.py文件，是不是启用了某些耗时的扩展（例如在没有源码时也启用了sphinx.ext.autodoc）。 - 美化样式：觉得样式难看？很简单，在
conf.py文件中添加一行：html_theme = 'sphinx_rtd_theme'，并确保你已经通过pip install sphinx_rtd_theme安装了这个主题。
最后，有一个至关重要的点需要明确：VSCode 的 RST 预览功能并不会读取你通过 Makefile 或手动执行 make html 后在 build/ 目录生成的最终文件。 它每次预览都是基于当前文件内容临时生成的，目的是为了提供快速的编写反馈。因此，要验证文档的最终排版和所有交叉引用是否正确，还是得在终端完整地运行一遍构建命令（如 make html），然后打开 _build/html/index.html 在浏览器中查看。这才是最终的验收标准。
