Jupyter

kernel 必须与环境匹配

Jupyter 内核（kernel）是「运行 notebook 的那个解释器」。装了 Jupyter 并不等于任何语言能跑 —— 每种语言都要有对应的 kernel 包，安装在同一个环境里。

Python 内核：

bashpip install ipykernel
python -m ipykernel install --user --name py311 --display-name "Python 3.11"

--name 是内部标识（字母数字与连字符，不能有空格），--display-name 是界面上显示的名字。R 内核同理：install.packages('IRkernel') 后执行 IRkernel::installspec(user = TRUE, name = 'ir', displayname = 'R')。

最常见的报错是 Jupyter kernel not found 或内核一直停在「connecting」：多半是 notebook 元信息里记录的 kernel 名与本机已安装的不一致。用 jupyter kernelspec list 列出清单，对不上的名字要么补装、要么在 Notebook 界面里手动换。

虚拟环境与内核的分工

conda / venv 解决「依赖版本冲突」，kernel 解决「Jupyter 能找到解释器」，两者正交。conda 环境不会自动出现在 JupyterLab 里，需要在每个环境里各装一次内核：

bashconda create -n stat python=3.11
conda activate stat
pip install ipykernel
python -m ipykernel install --user --name stat --display-name "stat (py3.11)"

换 kernel 比想象中麻烦 —— 它会重启内核，内存中的变量全部丢失，运行中的长任务尤其要当心。

nbconvert：批量导出才是正经用法

notebook 本质是 JSON（格式由 nbformat 定义），nbconvert 负责把它转成别的形态：

bashjupyter nbconvert --to html --execute report.ipynb      # 执行后导出 HTML
jupyter nbconvert --to markdown --execute report.ipynb  # 导出为 Markdown 文档
jupyter nbconvert --to python --stdout report.ipynb     # 导出为可执行脚本
jupyter nbconvert --to notebook --clear-output --inplace report.ipynb

最后一个用于清理输出，把 notebook 显著压小。

导出 PDF 报错多半是缺 LaTeX（.tex 找不到），装 TeX Live 即可，或改用 --to html 再用浏览器打印成 PDF。

版本控制上的麻烦

notebook 存的是含大量输出与执行计数的 JSON，Git diff 几乎无法阅读，两边各跑一次就会冲突。实用做法是输出不入库：把 *.ipynb 加进 .gitignore，把 notebook 当草稿、成品放 .py/.qmd。若必须提交，加一行 .gitattributes 写 *.ipynb binary 关闭 diff。

公式与输出的渲染

Markdown 单元格支持 LaTeX：行内用 $...$，独立公式用 $$...$$。常见问题是中文与公式混排时字间距不理想，或者 \text{} 里的中文显示为方块 —— 需要 \usepackage{ctex} 或改用 \mathrm{}。

输出乱码是另一类问题：Python 侧 print 的中文在 Windows 控制台常变问号，加两行即可：

pythonimport sys
sys.stdout.reconfigure(encoding='utf-8')

需要更系统的说明时，官方文档站有完整的 Jupyter 文档（在新标签页打开），安装、内核、notebook 格式都有独立章节。