如何在Sphinx中配置LaTeX physics包实现量子公式正常渲染

核心问题根因 #

你之前的配置完全混淆了不同输出链路的作用范围：

• latex_elements 定义的preamble内容，仅在Sphinx生成LaTeX源码、后续编译为PDF的流程中生效——这部分内容会被写入最终生成的.tex文件头部，供本地LaTeX编译器加载调用physics包。
• 你执行make html时，HTML页面的公式渲染完全走独立的浏览器端MathJax链路，根本不会读取你为本地LaTeX环境配置的规则，自然无法识别physics包提供的\ket这类自定义语法。

分步配置方法 #

1. 补全基础HTML渲染依赖
   Sphinx默认不会自动开启HTML端的数学渲染能力，需要在conf.py的extensions列表中加入sphinx.ext.mathjax，作为浏览器端公式渲染的基础组件。
2. 为MathJax配置physics包加载规则
   HTML端的公式渲染全靠浏览器加载的MathJax引擎完成，需要专门告诉MathJax在解析公式前先加载physics模块的能力。这部分配置属于项目通用配置段，不要放到LaTeX专属配置块里，参考代码：

   # conf.py 通用配置段
   extensions = [
       'sphinx.ext.todo',
       'sphinx.ext.mathjax'  # 新增HTML端数学渲染支持
   ]
   
   # 配置MathJax3启动时加载physics包能力
   mathjax3_config = {
       'loader': {
           'load': ['[tex]/physics']
       },
       'tex': {
           'packages': {'[+]': ['physics']}
       }
   }
   

3. 保留原有PDF输出配置
   你之前编写的LaTeX输出配置不需要删除，它本来就是为PDF编译流程准备的，和HTML端的配置完全独立、互不干扰：

   # -- LaTeX输出选项，原有配置直接保留即可
   latex_engine = 'xelatex'
   latex_elements = {'preamble': r'\usepackage{physics}'}
   

验证构建效果 #

配置完成后执行以下命令重新生成文档：

• 先执行make clean清理旧的构建缓存，避免旧资源影响渲染效果
• 再执行make html生成新的静态页面
• 打开生成的HTML文件，检查\ket{\psi}=\frac{1}{\sqrt{2}}(\ket{00}+\ket{11})是否可以正常渲染为带自动适配大小尖括号的量子态形式。

常见踩坑提醒 #

• 不要将HTML端的渲染配置放到LaTeX专属配置段，两个输出链路的配置完全独立、不互通
• 若使用4.0版本以下的旧版Sphinx，没有mathjax3_config选项，可以替换为旧版的mathjax_config写法加载physics包；目前优先使用MathJax3的配置方案，对physics包的命令支持更完整
• HTML端的公式渲染完全由浏览器端的MathJax实现，和本地安装的LaTeX环境没有关系，不需要为了HTML端的公式渲染专门在本地安装physics LaTeX包。

内容的提问来源于stack exchange，提问作者Green Hairy Mermaid