Typora中文学术主题Academic-Zh安装调优与PDF导出排错

简介：面向中文写作与学术排版场景的 Typora 主题包，基于官方 Academic 主题改造，正文字体改用华文中宋，等宽代码字体选用 CamingoCode，更贴合中文论文、课程报告与技术笔记的阅读观感。改动主要集中在代码块上：采用带外边框的样式，让代码片段在长文档中更容易辨认；同时兼容 div 右对齐与 center 居中写法，便于处理图表注释和居中排版。压缩包共 14 个文件，约 15.46MB，以 8 个 woff 字体文件为主，配套 2 个 css 样式表，分别负责主题入口和字体声明；另有 2 份 pdf 授权说明、1 份 txt 字体许可和 1 份 md 说明文档，整体体积主要来自中英文字体资源。已有 455 人学习下载。对于希望在不改变写作流程的前提下提升中文排版质感的用户，可以获得一套可直接使用的字体与样式组合，省去自行寻找中文字体、调整代码块边框和对齐方式所花费的调试成本。

1. Typora 默认主题写代码顺手，写中文论文就不行

Typora 装完自带的那套 GitHub 风格，写代码笔记很舒服，一旦落到中文学术稿上就不够用了：正文没有衬线、行距偏挤、标题从一级到四级糊成一片、表格边线和代码块底色也各走各的。所以很多人装完 Typora 的第一件事，就是找一套 Typora 中文学术风格主题。这类主题本质就是一坨 CSS，不编译、不装依赖、不动注册表，看着比装数据库简单一百倍，却最容易出问题：目录放错、版本对不上、字体没装、文件名带了中文，都会出现「明明放进去了，主题列表里就是没有」。这套 Academic-Zh 适合两类人：要写论文、写技术白皮书、导出 PDF 给别人看的人；以及只想要一份干净中文排版的普通用户。下面按我实际装的顺序，从版本对齐一路写到装完怎么验。

2. 装前把版本和目录对齐：Typora 主题目录、字体与文件分工

装主题失败的人里，超过一半不是 CSS 写错了，是文件根本没进对位置。Typora 的主题目录不在安装目录里，而在用户数据目录下。很多人跑去C:\Program Files\Typora里翻，翻不到themes文件夹，就下结论说这软件不支持自定义主题。其实在菜单里点两下就能打开。这一章把三件事对齐：目录在哪、版本差在哪、字体有没有。

2.1 三个平台的主题目录到底在哪

先把路径摆出来，再用命令确认，别靠记忆。Windows 是%APPDATA%\Typora\themes，展开就是C:\Users\<用户名>\AppData\Roaming\Typora\themes；Linux 常规安装是~/.config/Typora/themes；macOS 有两个可能的位置，早期版本挂在abnerworks.Typora下，较新版本直接在Typora下，两个都看一眼最省事。

# macOS：两个路径都可能存在，先看哪个有内容 ls -d ~/Library/Application\ Support/Typora/themes 2>/dev/null ls -d ~/Library/Application\ Support/abnerworks.Typora/themes 2>/dev/null # Linux：常规安装 ls -d ~/.config/Typora/themes # Linux：如果是 flatpak / snap 安装，数据目录被沙箱包了一层 ls -d ~/.var/app/*/config/Typora/themes 2>/dev/null

这段的作用是「确认存在」，不是「创建」。2>/dev/null是为了让不存在的路径安静跳过，不然满屏No such file or directory反而看不清哪个是真的。如果几条命令都没输出，说明 Typora 还没启动过，或者你是通过沙箱包安装的，去~/.var/app/底下按包名找。

Windows 用 PowerShell 更直观：

# 打印用户主题目录，并列出里面已有的 css $dst = Join-Path $env:APPDATA "Typora\themes" Write-Output $dst Get-ChildItem $dst -Filter *.css | Select-Object Name

$env:APPDATA就是C:\Users\<用户名>\AppData\Roaming，Join-Path负责拼路径，比手写反斜杠安全。Select-Object Name只输出文件名，方便你对照是不是已经有github.css、night.css这些自带主题——有它们，说明目录是对的。

提示：最保险的方式永远是从菜单走，偏好设置 → 外观 → 打开主题文件夹。系统会直接弹文件管理器，省掉所有路径猜测，尤其是 macOS 和沙箱安装的 Linux。

2.2 版本差异：themes 与 style，选错目录等于白装

Typora 的主题目录名改过。早期 0.11 前后的版本用的是style目录，之后统一成themes。这两个名字不能混用：你把 css 放进style里，新版程序根本不扫这个目录，界面上当然什么都不会变。更隐蔽的情况是同一台机器装了两个版本，一个稳定版一个测试版，你改的是 A 的目录，打开的是 B 的程序，改十遍都没反应。

确认版本的方式很简单，帮助 → 关于，看版本号。我的建议是：新版本一律认themes，别去碰style；如果目录里同时存在style和themes，说明你从老版本升上来过，以themes为准。

自定义样式的能力也随版本变。较新的 1.x 版本支持「按主题名生效」的覆盖文件，也就是主题叫academic-zh，你就可以新建academic-zh.user.css，只影响这一个主题；而很早的版本只有base.user.css，一改就是全局生效。这个差异决定了第 3.4 节该怎么写覆盖文件——先确认自己的版本支持哪一种，再动手。

还有一个被忽略的点：文件名。扩展名必须是小写.css，Linux 和部分 macOS 文件系统对大小写敏感，XX.CSS在 Linux 上就是不会被识别；文件名里别塞中文和空格，某些版本读取远程资源或者生成主题列表时会出岔子，显示成乱码或者干脆漏掉。

2.3 字体前置：中文字体没装，CSS 写了也白写

中文学术风格主题的观感，七成来自字体，三成才是间距和线宽。CSS 里写的是字体族名，系统里没有这个字体，浏览器内核就静默回退到默认字体，通常是个无衬线体。结果就是你装了主题，看起来跟没装差不太多，还以为是主题坏了。

把常见的族名和来源对一遍：

关键一条血泪经验：CSS 的font-family里要写英文族名，别写「思源宋体」四个字。Windows 上部分渲染路径对中文字体族名的匹配很差，写中文名经常匹配不上，而英文 PostScript 名几乎处处认。字体装完之后必须重启一次 Typora，字体缓存是在启动时读的，不重启照样回退。

确认字体有没有装，各平台跑一条：

# Linux：列出系统里所有中文字体，看有没有 Source Han / Noto CJK fc-list :lang=zh family | sort -u | head -20

fc-list是 fontconfig 的工具，:lang=zh过滤中文语系，family只输出族名，sort -u去重。输出为空说明系统没装任何中文字体，先装字体再谈主题。macOS 打开「字体册」搜 Source Han 就行；Windows 在设置 → 个性化 → 字体里翻，或者直接看C:\Windows\Fonts下有没有对应文件。

2.4 主题目录里每类文件干什么

装之前先弄清楚themes目录里放什么，能省掉后面一轮折腾：

最后一行特别说明一下：Typora 只扫描themes目录的第一层，子文件夹里的 css 一律不认。有些主题包解压出来是「一个文件夹套着 css」，你整包丢进去，主题列表里就是空的。这是第 5 章要展开的坑之一。

3. 安装 Academic-Zh：拷贝、启用与第一页渲染

目录和字体对齐之后，安装本身只有三步：把 css 放到themes根目录、从菜单里选主题、看第一页渲染是否正常。真正花时间的是第三步之后的微调。这一章按顺序走，每一步都给验证方法，确保做完就知道成没成。

3.1 解压后先看结构，别整包乱丢

解压出来先ls一眼，看清楚哪个是主文件、哪个是给你改的模板。判断标准很朴素：主主题 css 通常是那个文件名最短、体积最大、里面有大量选择器的；带.user.css后缀的是留给你改的覆盖模板；说明文档和预览图不影响安装。

# 解压后先看结构，注意 css 是不是在根层 unzip -l Typora-Academic-Zh.zip | head -30 # 解开后单独列一下 css find Typora-Academic-Zh -maxdepth 1 -name "*.css"

unzip -l只列内容不解压，先看压缩包里有没有多余的层级；find -maxdepth 1限制只找第一层，如果这边输出为空、而find不带深度限制又能找到，那说明 css 埋在了子目录里，需要手动提出来。这一步花十秒钟，能省掉后面「为什么主题列表里没有」的半小时。

注意：不要把整个解压出来的文件夹拖进themes。要拖的是文件夹里的.css文件本身。文件与目录的区别，在这一步上是决定性的。

3.2 放文件：三平台命令与验证

Windows 用 PowerShell，先确认目标目录存在再拷贝：

# 目标目录不存在就先建，存在则跳过 $dst = Join-Path $env:APPDATA "Typora\themes" if (-not (Test-Path $dst)) { New-Item -ItemType Directory -Path $dst | Out-Null } # 只拷 css，避免把说明文档和截图一起塞进去 Copy-Item .\Typora-Academic-Zh\*.css -Destination $dst -Force # 拷完立刻核对 Get-ChildItem $dst -Filter *.css | Select-Object Name, Length

-Force表示目标已存在时直接覆盖，升级主题时不用先删；Length输出文件字节数，用来确认不是拷了个 0 字节的空文件——U 盘传输中断、压缩包损坏都会造成这种情况，而空 css 在主题列表里照样显示，选了之后界面一片白，很难查。

macOS 和 Linux 用cp：

# -R 递归、-v 打印每个被拷的文件，方便肉眼核对 cp -Rv ./Typora-Academic-Zh/*.css ~/.config/Typora/themes/ # macOS 换成下面这条 # cp -Rv ./Typora-Academic-Zh/*.css ~/Library/Application\ Support/Typora/themes/ # 验证：目标目录里的 css 数量应该比之前多 ls -l ~/.config/Typora/themes/*.css

-v会逐个打印xxx.css -> /path/xxx.css，这是最省事的核对方式，比拷完再ls更直观。如果提示权限不足，多半是你把目标写成了安装目录，回头确认路径。

3.3 启用主题：菜单、重启与首次渲染

文件到位后，打开 Typora，偏好设置 → 外观 → 主题，下拉列表里应该能看到新主题的名字（就是 css 文件名去掉后缀）。选中，界面立刻变。如果列表里没有，别急着改 css，先做两件事：确认 css 在themes第一层、确认扩展名是小写。

选中之后如果界面没变化，或者只变了一半（比如正文变了、代码块还是老样子），按顺序试：先切换回自带主题再切回来，逼一次重绘；不行就完全退出 Typora 再启动，macOS 上注意是退出不是关窗口；再不行就重启系统字体缓存（装完字体后尤其需要）。这三步能解决九成的「装了没反应」。

首次渲染会有一点延迟，尤其是文档里有大表格、公式块或长代码块时，字体加载和排版计算都要时间。学术稿里公式多的时候，滚动会有一瞬间的重排，这是正常的，不是主题写崩了。

3.4 不改主题文件：user.css 的覆盖机制

主题本体不要直接改。原因很实际：作者更新一版、你覆盖一次，你的改动全没了。正确做法是用覆盖文件，加载顺序是主题 css 先、[主题名].user.css后、base.user.css最后（具体以你的版本支持为准），后加载的规则会覆盖前面的同名属性。

第一步先确认覆盖文件到底有没有被读到，用一个显眼的自检样式：

/* 自检：给编辑区加一圈红边，能看见就说明 user.css 被加载了 */ #write { outline: 2px solid red; }

#write是 Typora 正文容器的固定 id，所有正文内容都在里面。加outline而不是border，是因为outline不占布局空间，不会把整页宽度顶歪。保存后切一次主题再切回来，看到红边就说明机制通了，把这段删掉，开始写真正的覆盖规则。

文件名要跟主题 css 同名，主题叫academic-zh.css，覆盖文件就叫academic-zh.user.css，两者放在同一个themes目录下。如果你的版本不支持按主题名覆盖，就退化到base.user.css，规则写一样，代价是它也会影响自带主题，所以写完记得在别的主题下也扫一眼。

4. 参数调优：字号、行距、页边距和代码块怎么改

主题默认值面向「大多数人」，而你只有自己一个用户。这一章的每条规则都写在academic-zh.user.css里，不碰主题本体，将来升级直接覆盖过去。先说明一个前提：如果主题文件开头有一段:root { --xxx: ... }的变量定义，优先改变量，最省事；如果没找到变量段，就用下面这种直接覆盖选择器的方式，效果一样。

4.1 正文字号与行高

中文和英文的排版参数不是一回事。英文靠词间空格断行，中文是方块字，行距不够会糊成一整块，字距太紧又显得挤。

/* 正文排版：字号、行距、字距、栏宽 */ #write { font-size: 16px; /* 中文正文 15–17px 比较稳，再大导出 PDF 会溢页 */ line-height: 1.85; /* 学术稿常用 1.7–2.0，1.85 兼顾密度和呼吸感 */ letter-spacing: 0.02em; /* 中文轻微加宽，避免笔画贴在一起 */ max-width: 820px; /* 栏宽，超过 900px 长行阅读会累 */ margin: 0 auto; /* 栏宽收窄后居中 */ text-align: justify; /* 两端对齐，中文断行更整齐 */ }

逐条说取舍：font-size为什么卡在 16px 附近？因为 Typora 的编辑区是屏幕阅读场景，14px 以下长时间看眼睛累，18px 以上一屏放不下几行，写长文档要不停滚。line-height1.85 是我试出来的折中值，1.6 太紧、2.0 太散、翻页时容易断句。letter-spacing用em而不是px，字号变了比例还在。max-width是关键参数，默认全宽在大显示器上会出现一行七八十个字的情况，眼睛回行会找错行。

text-align: justify在中文里效果明显好于英文，因为汉字等宽，两端对齐不会出现英文那种巨大的词间空隙。别指望hanging-punctuation帮你做标点悬挂，主流渲染内核还没实现，写了也不生效。

4.2 标题层级与中文字重

学术稿的标题层级必须一眼分得清，靠的不是字号一路放大，而是字号、字重、留白的组合。

/* 标题层级：字号递减、上下留白递增 */ #write h1 { font-size: 1.9em; margin: 1.6em 0 0.8em; font-weight: 700; } #write h2 { font-size: 1.5em; margin: 1.4em 0 0.6em; font-weight: 700; } #write h3 { font-size: 1.25em; margin: 1.2em 0 0.5em; font-weight: 600; } #write h4 { font-size: 1.05em; margin: 1em 0 0.4em; font-weight: 600; } /* 中文标题不要用纯黑，深灰更耐看 */ #write h1, #write h2, #write h3 { color: #1a1a1a; }

em单位让标题跟着 4.1 里的正文字号联动，你改正文，标题自动等比缩放，不用回头再调一遍。margin上大下小是有意的：标题和它所属的正文贴得近，和上一节离得远，读者才能看出归属关系。font-weight用 600 而不是 700，是因为思源黑体在 700 时笔画会糊到一起，尤其小字号下。

如果主题带自动编号（counter实现的章节号），改字号之后编号的位置可能会偏，检查一下h1::before的margin-right是否还合适。

4.3 代码块、表格与引用

学术稿里代码块和表格的比例不低，这两块的默认样式经常和正文打架：正文衬线、代码块也跟着衬线，或者代码块字号跟正文一样大，一眼分不出哪段是代码。

/* 代码块：等宽字体 + 稍小字号，和正文拉开层次 */ .md-fences, .md-fences code, pre { font-family: "JetBrains Mono", "Cascadia Code", Consolas, monospace; font-size: 13.5px; line-height: 1.6; border-radius: 4px; } /* 表格：细线、紧凑内边距，别让边框抢戏 */ #write table { border-collapse: collapse; width: 100%; } #write th, #write td { border: 1px solid #d0d7de; padding: 6px 10px; } /* 引用块：只留左侧竖线，去掉整块底色 */ #write blockquote { border-left: 3px solid #c8c8c8; background: transparent; padding-left: 14px; }

.md-fences是 Typora 代码块容器的类名，pre兜底，保险起见两个都写。字号 13.5px 是刻意比正文小一档，因为等宽字体视觉上比同字号的汉字大，写 16px 会显得特别肥。border-collapse: collapse合并相邻边框，否则表格会出现双线，打印出来特别难看。引用块去掉底色是我个人偏好，学术稿里引用多，每块都带灰底会显得很碎。

4.4 导出 PDF 的打印参数

屏幕好看不等于打印好看。导出 PDF 走的是打印样式，很多在屏幕上生效的规则在这里会被重置，所以必须单独写一段@media print。

@media print { /* 打印用磅值，屏幕像素在纸面上不准确 */ #write { font-size: 11pt; line-height: 1.8; max-width: 100%; } /* 标题别孤零零留在页底 */ h1, h2, h3 { page-break-after: avoid; } /* 代码块、表格、图不要被切成两半 */ pre, table, figure { page-break-inside: avoid; } /* 隐藏屏幕专用的元素 */ .typora-export-sidebar, .md-toc-content .md-toc-item a::after { display: none; } }

pt是物理单位，10.5pt 到 11pt 是中文论文正文的常见区间，屏幕上看着小，印出来正好。page-break-after: avoid让标题不落在页面最后一行，否则会出现「标题在页尾、正文在下一页」的经典事故；page-break-inside: avoid同理，防止一张表格横跨两页被切碎。最后一条是清理导出时的辅助元素，具体类名以你的主题实际结构为准，写之前先在开发者工具里确认一下，别照抄。

页边距建议在导出对话框里设，比@page { margin }稳，后者在部分版本上不生效，而且会在屏幕预览时留下意外空白。

5. 常见问题排查：主题不生效、字体回退、代码块错位的五个坑

下面五条是我和身边人真实翻过的车，每条都按「现象 → 原因 → 解决」写，方便对着症状直接查。

5.1 主题列表里根本没有这一项

现象：css 明明拷进themes了，打开偏好设置的下拉列表，还是只有自带的那几个。

原因有三个。一是 css 放在了子文件夹里，Typora 只扫第一层；二是扩展名不是小写.css，Linux 大小写敏感会直接忽略；三是拷到了旧版本的style目录，而程序读的是themes。

解决：进themes目录ls一眼，确认文件就在这一层；Windows 上把「隐藏已知文件类型的扩展名」关掉，避免真实文件名是academic-zh.css.txt；如果目录里同时有style和themes，把 css 挪到themes下再重启。

5.2 主题生效了，但字体明显回退

现象：界面风格变了，正文还是那个默认的无衬线，跟主题截图完全不是一回事。

原因：CSS 里指定的字体族系统里没有，或者装了但 Typora 是在装字体之前启动的，字体缓存没刷新。

解决：先用fc-list :lang=zh或字体册确认字体真的在；确认在的话，完全退出 Typora 再启动，别只关窗口；还不行就检查 CSS 里写的是不是英文族名，把「思源宋体」改成Source Han Serif SC再试。字体族名写错一个字母都会静默回退，没有任何报错，只能靠肉眼比对。

5.3 代码块行号、换行和背景错位

现象：代码块左边多出一条竖线、行号跑到框外面、长代码行换行之后背景色断掉。

原因：覆盖规则只改了一半。.md-fences控制外框，pre和.CodeMirror-line控制内部行，只改外框不改内层，两层的line-height和font-family不一致，就会错位。

解决：等宽字体和line-height要同时写给.md-fences、.md-fences code、pre三个选择器，别只写一个；行号列的宽度是主题里单独定义的，改字号之后要同步调，不然数字会被裁掉。

5.4 导出 PDF 后行距变大、标题跑到页尾

现象：屏幕上排版完美，导出的 PDF 里行距松了一截，或者标题单独躺在页面最后一行。

原因：屏幕样式和打印样式是两套。像素单位在纸面上换算后会偏，分页规则默认也没有任何约束。

解决：单独写@media print，字号换成pt，加上page-break-after: avoid和page-break-inside: avoid；页边距在导出对话框里设，别写进 CSS。

5.5 改完 CSS 界面直接崩了

现象：某个标题突然变得巨大，或者整页只剩白底黑字的裸样式。

原因：少了括号、少了分号，或者一个规则写得过宽（比如直接写* { }），把 Typora 自己的布局规则也覆盖掉了。

解决：改之前先备份user.css；一次只改一块，改完立刻切主题看效果，别一口气写五十行再刷新；崩了就先把user.css改名成user.css.bak重启，界面一定回到安全状态，再一段一段加回去。这算是排错时最有用的补救办法。

6. 验证：三份样张跑通，才算真装完

主题能显示不等于装好了。我见过太多「界面上看着挺好，一导出 PDF 全乱」的情况，所以每次装完主题，我都会跑一套固定的三份样张，全过了才算收工。

第一份是纯中文长文。找一篇两三千字的连续中文，粘进去看三件事：行距是不是从头到尾一致（有没有某段突然变紧）、两端对齐有没有出现某行字距被拉得特别开、段落首行缩进是否统一。第二份是中英混排加公式加表格加代码的混合稿，专门看元素之间的间距会不会打架——公式块下面紧跟代码块时，两者的上下留白是不是对称。第三份是导出，直接把第二份导出成 PDF，翻一遍分页，重点看表格和代码块有没有被切开、标题有没有落在页尾。

下面这张表是我自己的验收清单，逐项打勾：

最后一行是我额外加的，因为学术稿里经常出现无法断行的英文术语和五六列的宽表格，栏宽一撑破，整页排版全乱。测的时候故意粘一个两百字符不含空格的字符串进去，看是换行还是溢出，溢出的就在user.css里补word-break: break-word。

从那以后我每次装任何编辑器主题，都会强制走一遍「三份样张 + 一张对照表」，不再相信「看起来变了就是装好了」这种判断。主题这东西玄学的地方在于，它不出错的时候你完全感觉不到它的存在，一出错就是导出前十分钟才发现，返工成本全压在最后。希望这套流程能帮你少走一次弯路，压缩包拿到手之后按第 3 章的路径放进去，切一次主题就能看到效果。

本文还有配套的精品资源，点击获取