根本原因是VSCode未调用安装了docutils或sphinx的Python环境；需手动安装对应包、正确配置解释器路径、确保文件关联为reStructuredText，并使用“Preview with Sphinx”命令才能正常预览。
VSCode预览RST文档空白或报ModuleNotFoundError
根本原因就一个：VSCode没调用到装了docutils或sphinx的Python环境。它不会自动帮你装包，也不会猜你用哪个解释器。
常见现象包括右键“Preview”无反应、预览窗口纯白、控制台报ModuleNotFoundError: No module named 'docutils'。
- 必须用
pip install docutils（基础渲染）或pip install sphinx sphinx-rtd-theme（带主题和指令支持） - 如果你在虚拟环境中开发，确保VSCode选中的Python解释器路径和
pip所在路径一致——比如.venv/bin/python或.venv\Scripts\python.exe - 按
Ctrl+Shift+P→ 输入Python: Select Interpreter→ 仔细核对路径，别选系统Python或conda base - 打开任意
.rst文件，右下角状态栏语言模式必须是reStructuredText；如果不是，点击它 →Configure File Association for '.rst'→ 设为reStructuredText
为什么点“Preview”没效果，而必须选“Preview with Sphinx”
VSCode默认的Preview按钮走的是docutils极简渲染路径，不加载conf.py、不识别:ref:或:toctree:等Sphinx指令，也没有CSS样式，看起来像纯文本。
想看到真实效果，必须主动右键 → 找到reStructuredText: Preview with Sphinx（注意名字里带Sphinx）。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
- 该命令会尝试读取项目根目录或
source/下的conf.py；找不到就fallback到docutils，但不会报错，只会显示简陋结果 -
conf.py和index.rst不是可选项，是Sphinx预览启动前提——没有它们，连首页都打不开 - 预览窗口不自动刷新，每次修改后必须
Ctrl+S保存才会更新
插件设置里restructuredtext.confPath填什么
这个配置项只影响插件查找conf.py的起点路径，不负责执行构建逻辑。
- 如果项目有标准Sphinx结构（如
docs/source/conf.py），就填docs/source - 如果
conf.py就在项目根目录，就填.或留空（插件会从当前打开的文件所在目录向上找） - 填错不会报错，只是导致Sphinx功能失效：主题不加载、扩展不生效、路径解析失败
- 不要填完整路径如
/home/user/myproj/docs/source/conf.py，插件只接受目录路径
用sphinx-autobuild替代插件预览更可靠
VSCode插件预览依赖GUI线程和路径解析，容易卡住或失联；而sphinx-autobuild是独立进程，在终端里跑，稳定且响应快。
- 安装：
pip install sphinx-autobuild - 在
source/目录下运行：sphinx-autobuild -b html . ../build/html - 浏览器访问
http://localhost:8000，改完.rst保存即实时刷新 - 比插件预览多出热重载、错误高亮、终端日志反馈，适合中大型文档项目
真正容易被忽略的点是：Sphinx预览不是“开箱即用”的功能，它本质是把本地Python环境里的工具链暴露给编辑器。任何一环断开——解释器错、路径错、命令选错、文件缺失——都会静默失败，只留一个空白页。盯住conf.py、index.rst、解释器路径、右键菜单名称这四个点，基本能覆盖90%的故障场景。
