能跑通Sphinx本地预览的关键是sphinx-autobuild链路打通、路径编码干净、index.rst存在且被toctree引用；需安装sphinx和sphinx-autobuild，终端运行sphinx-autobuild监听变更，确保index.rst为UTF-8无BOM并含toctree，Sublime插件仅提供语法支持，构建问题须查终端日志。
能跑通 Sphinx 本地预览，关键不在 Sublime 插件装得多，而在 sphinx-autobuild 链路打通、路径编码干净、index.rst 存在且被引用——三者缺一不可。
确认 sphinx-autobuild 可执行且监听生效
Sublime 自带的 Ctrl+Shift+R 预览本质是调用 sphinx-build 一次性构建，不监听变更；真正“保存即刷新”必须靠终端运行 sphinx-autobuild。
- 先装完整环境：
pip install sphinx sphinx-autobuild（只装docutils不够，数学公式、自定义角色会失效） - 终端进入你的文档根目录（含
conf.py的目录），运行：sphinx-autobuild -b html source build（假设源码在source/下） - 若报错
command not found: sphinx-autobuild，说明没装或 PATH 没生效；Windows 用户检查是否勾选了安装时的 “Add Python to PATH” - 成功后浏览器打开
http://localhost:8000，改任意.rst文件并保存，页面应自动刷新
确保 index.rst 存在、UTF-8 无 BOM、含 toctree
Sphinx 默认只认 source/index.rst，且必须被 toctree 指令显式包含，否则新增文件全被忽略——这不是插件问题，是 Sphinx 本身行为。
- 手动创建
source/index.rst，内容至少包含：.. toctree:: :maxdepth: 1 index
- 所有其他
.rst文件（如chapter1.rst）必须加进某个toctree指令里，哪怕只是写在index.rst中 - Sublime 中右下角状态栏点击编码名 → 选
UTF-8（不是UTF-8 with BOM），中文路径务必避免（例如C:/我的文档/docs会导致sphinx-autobuild静默退出）
Sublime 的 reStructuredText 插件只负责语法支持，不负责构建
插件名是 reStructuredText（不是 rst 或 rest），它只提供高亮、指令折叠、:role: 补全等功能，和预览无关。
- 安装方式：Ctrl+Shift+P →
Package Control: Install Package→ 输入reStructuredText→ 回车 - 若打开
.rst文件后右下角显示Plain Text，需手动点击状态栏切换为reStructuredText - 如果用了 Anaconda/pyenv/虚拟环境，需在
Preferences → Package Settings → reStructuredText → Settings – User中指定解释器：{"python_binary": "C:/path/to/python.exe"}（Windows 路径用正斜杠） - 别指望它解决构建失败；错误堆栈永远在终端里，不是 Sublime 控制台（Ctrl+`）
Chrome 预览时禁用缓存，conf.py 里别写错 source_suffix
浏览器缓存会让修改后的标题、段落不更新；conf.py 中一个字符写错，Sphinx 就可能静默跳过整个构建流程。
- Chrome 打开 DevTools（F12）→ Network 标签页 → 勾选
Disable cache -
source_suffix = '.rst'必须是字符串，不是列表；写成['.rst']会导致sphinx-autobuild启动失败且无明确提示 -
extensions列表中扩展名必须全小写、带完整路径，例如'sphinx.ext.autodoc'写成'autodoc'或'Sphinx.ext.autodoc'都会加载失败
最容易被忽略的是：Sphinx 构建失败时往往不报错，只输出空 HTML 或跳过文件——这时候得看终端里 sphinx-autobuild 的实时日志，而不是反复点 Sublime 的预览快捷键。
