MarkText 使用指南：开源所见即所得 Markdown 编辑器配置与避坑

写 Markdown 的人，最烦的就是“左边写右边看”那种割裂感。我之前在 Typora 和 VS Code 之间反复横跳了很久，直到后来折腾到 MarkText 这个开源编辑器，才算是把日常写作、技术笔记、博客草稿这几条线统一到了一个工具里。MarkText 是一个主打所见即所得的 Markdown 编辑器，核心思路是“你写什么，屏幕上就实时渲染什么”，同时保留了源代码模式，适合写技术文档的人做精细控制。

这篇文章就把我实际使用 MarkText 过程中整理出来的安装步骤、界面逻辑、快捷键习惯、图床配置、常见坑和不顺手的解决办法一次说清楚。无论你是准备把 MarkText 当作主力 Markdown 工具的新手，还是想从 Typora 换过来的老用户，只要照着做，基本可以少走不少弯路。

1. MarkText 到底是一个什么样的编辑器

1.1 为什么我从 Typora 转到了 MarkText

实话实说，Typora 的体验确实好，但它的定位是商业软件，而且封闭。我的需求很简单：希望有一个支持实时渲染、跨平台、最好还能自己折腾配置的 Markdown 编辑器。MarkText 正好是这条路线的开源替代品。它的界面默认就是干净的全屏写作视图，背景、配色、排版都可以自己换，连整个界面的主题都有好几套。

我用它写的第一个文档是一篇带表格、代码块、嵌套列表和一张本地图片的技术方案。整个过程中除了插入图片时路径处理稍微注意一下之外，其余基本没有打断写作状态。对于每天都要写东西的人来说，“不打断”这三个字比什么功能都重要。MarkText 把预览和编辑做成了同一个视图，你在任何位置敲字符，渲染结果立刻就变，不用像传统编辑器那样在“编辑”和“预览”两个标签页之间来回切换。

1.2 MarkText 与同类编辑器的简单对比

很多人会纠结它和 Typora、Obsidian 之间怎么选。我的看法是：别急着把所有笔记类工具都塞进同一个目录。Typora 胜在精致和轻量，Obsidian 强在以双链为核心的笔记管理，而 MarkText 的定位更纯粹——它就是一个让你专心写 Markdown 的编辑器，不搞复杂的知识库体系。

从使用体感上说，MarkText 最像 Typora 的地方就是段落内实时渲染，你不需要做任何额外操作，光标落在哪一段，那一段就进入“可编辑状态”，光标移开后就显示成排版后的效果。这个体验在写长文档时特别有意思，因为你永远能看到最终的排版效果，又随时能调整，不会像 Word 那样来回切换到让人头大。MarkText 原生支持 CommonMark 规范和 GitHub Flavored Markdown（GFM），对于写博客、写项目 README、写接口文档这些场景完全够用。

2. 下载、安装与环境适配

2.1 下载渠道与版本选择

MarkText 的官方下载渠道主要是 GitHub Releases 页面。进入 Releases 页面之后，你会看到marktext-setup-x64.exe、MarkText-x86_64.AppImage、marktext.dmg这些文件。Windows 用户直接下载 exe 安装包，macOS 用户下载 dmg，Linux 用户按自己的桌面环境选 AppImage 或 deb 包。

这里有个容易踩的坑：不要看到新版本就无脑冲。MarkText 官方维护节奏其实比较慢，某些版本在 Windows 上有输入法兼容问题。如果是为了稳定使用，我建议优先选择最新的 release 版本，同时留意 issue 区有没有大面积报问题的反馈。如果碰到安装后白屏或者打不开的情况，可以往下看第六部分的排查方法。下载前留意一下安装包的位数，现在绝大多数机器都是 64 位系统，直接选x64文件。

2.2 老系统兼容性说明

热词里有人问“MarkText 支持 XP 吗”，这里直接给结论：不支持。MarkText 基于 Electron 开发，而新版 Electron 对操作系统版本有最低要求，Windows XP 已经远远超出了支持范围，就算强行安装，大概率也是白屏或者运行报错。如果你还在 XP 环境下工作，只能考虑更老旧的 Markdown 编辑器，或者干脆换一个 Markdown 在线编辑方案。

Windows 7 的话，要看具体版本。MarkText 较早期的版本在 Win7 上运行基本没毛病，但如果是特别新的版本，可能会因为缺少系统运行库而打不开。遇到这种问题，先把 Windows 的“通用 C 运行库（Universal C Runtime）”补丁装上，再安装 Visual C++ Redistributable，一般就能解决。我在一台老联想笔记本上就是这么处理的，装完这两个依赖，MarkText 就可以正常跑起来，只是打开大型文档时略微吃力。

2.3 安装后的第一轮设置

安装完成后，第一次打开界面是英文的，别急着找“中文设置”按钮，先看一眼整个工作区。左侧是文件树和搜索面板，中间是编辑区，底部有一个状态栏，显示字数、所在行、语法模式等信息。如果不小心把侧边栏关了，可以通过菜单里的View -> Sidebar或者快捷键Ctrl+J重新打开。

在开始写正式文档之前，建议先把自动保存选项确认一下。MarkText 默认情况下在输入过程中会维护一个本地缓冲区，即使你没手动保存，一般也不容易丢内容，但为了稳妥，还是建议及时Ctrl+S养成习惯。另外，在File -> Preferences里可以调整字体大小、行间距和主题。我一般会把字体调到 16 号，行间距稍微拉大一点，长时间看起来眼睛不容易疲劳。

3. 写作体验：编辑模式与快捷键

3.1 三种编辑模式到底怎么切换

MarkText 有四种视图模式：源代码模式、打字机模式、专注模式，以及默认的实时渲染模式。实时渲染模式就是默认所见即所得的状态；源代码模式会把你正在编辑的整篇文档切回纯 Markdown 文本，适合做批量查找替换的时候使用；打字机模式会让当前编辑的行始终保持在屏幕正中间，方便长时间连续输出；专注模式会把你正在写的一段高亮，其它段落变淡，减少视觉干扰。

实际操作中，我不建议一直开着专注模式。因为 Markdown 文档通常包含表格、代码块这些不能硬缩进排版的元素，专注模式只是视觉变淡，并不能真正“隐藏”其它内容，有些场景反而会误导你对排版效果的判断。比较合理的用法是：日常写作用实时渲染模式，大范围调整时切到源代码模式，需要集中处理某一章的时候临时打开专注模式。

切换视图的快捷键我在日常使用中会一直用：Ctrl+E打开源代码模式，Ctrl+Shift+T切换专注模式，Ctrl+Shift+M切换打字机模式。这几个按钮在菜单中的位置不太明显，直接记快捷键效率更高。

3.2 高频快捷键整理

MarkText 在快捷键设计上基本保持了主流 Markdown 编辑器的惯例。为了方便读者直接当作速查表，我把实际使用频率最高的快捷键列在下面：

写 Markdown 有一个底层逻辑：标题、列表、引用这类结构尽量用手指完成，不要依赖鼠标去点工具栏。因为 Markdown 本身是纯文本结构，快捷键敲出来的语法和手写#、-、>在本质上是同一回事，但快捷键不会让你下意识地切换到“鼠标操作模式”，这对保持写作状态非常有帮助。

3.3 表格、代码块和任务列表的实际体验

MarkText 对 GFM 表格的支持做得比较舒服。你只要写一个类似下面这样的表格，编辑器会自动把列宽对齐，并且渲染出起来直接就是带边框的表格样式：

| 工具 | 定位 | 适合场景 | | --- | --- | --- | | MarkText | 独立编辑器 | 日常写作、方案文档 | | Typora | 独立编辑器 | 追求精致体验的用户 | | Obsidian | 笔记管理 | 双链与知识库搭建 |

光标停到表格某一格上时，可以通过右键菜单插入新行或新列，这个操作要比手动改管道符方便太多。代码块对技术写作者来说更是刚需，MarkText 支持 40 多种语言的语法高亮。写代码块时，在开始的三个反引号后面直接写语言名，比如```python，编辑器会立刻按对应语法配色渲染。

任务列表也是平时用得很多的语法。写一个- [ ]开头，MarkText 会渲染出可以勾选的复选框。点击复选框后，源码里会同步变成- [x]，这对我维护工作清单特别友好。

4. 进阶功能配置：公式、图片与导出

4.1 数学公式渲染

MarkText 内置了 KaTeX，可以渲染 LaTeX 格式的数学公式，这对理工科写作来说是最大的加分项之一。写行内公式时用$...$包起来，比如$E=mc^2$；写独立公式时用两个美元符号包起来，比如：

$$ \frac{1}{n}\sum_{i=1}^{n}(x_i - \bar{x})^2 $$

这里要提醒一下：MarkText 的公式渲染在缺失某些宏包时会把整条消息显示为红色错误提示，但不会影响保存。如果你是从 Typora 迁移过来的，原本写在文档里的公式大概率没有问题，因为两者都基于 LaTeX 语法。需要注意的一点是行内公式两边不能有空格，否则会被当作普通文本处理。如果你发现写了$ 公式 $结果没有渲染，第一反应就是把空格去掉。

4.2 图片管理与 PicGo 图床配置

图片是 Markdown 写作中最容易翻车的一环。MarkText 默认情况下，粘贴一张截图进去时，会自动把图片复制到当前文档所在目录下的某个文件夹里，并生成相对路径引用。这样做的好处是文档移动位置后图片跟着走，不会出现链接失效。

但如果你写的是博客文章，最终提交到一个不支持相对路径引用的平台，那就麻烦了。这时候就需要配置图床。MarkText 在图床上主要靠 PicGo 作为外部工具联动。简单理解就是：你复制一张图片，MarkText 调用 PicGo，把图片上传到指定的对象存储或者图床服务，然后把生成的远程链接写入文档。

配置路径在File -> Preferences -> Image Uploader里。如果你本机安装了 PicGo，选择 PicGo 作为上传器，并填上 PicGo 的监听端口，默认是36677，然后在 PicGo 里把上传服务商配置好。实际操作中，我踩过一个坑：win7 系统下老版本的 PicGo 和新版 MarkText 联动时可能出现上传成功但链接未回填的问题，后来把 PicGo 升级到新版本就没事了。如果你不打算上图床，还有一种折中的做法：在 MarkText 里设置图片复制到固定目录，比如assets，然后通过版本管理统一同步图片。这种方法适合博客仓库里附带图片资源的场景。

4.3 导出 PDF 与 HTML

MarkText 的导出能力不算特别强，但对于日常文档交付够用。导出入口在菜单File -> Export，支持导出 PDF 和 HTML。导出 PDF 时，它实际上是先生成 HTML 再打印成 PDF，所以你在界面里看到的分页效果不一定完全等于纸张分页。如果你的文档里有大段代码块和表格，建议导出前在预览窗口检查一下换行是否正常，必要时调整页面边距和字体大小。

导出 HTML 适合用于快速发布成网页，或者作为后续排版工具的中间格式。不过 MarkText 导出的 HTML 严格来说是一个渲染后的独立页面，带有内联样式，直接拿来嵌入其它网页可能需要二次清理。相比起来，我更常用的是直接复制 Markdown 源码到博客后台，只在需要给客户交付正式文档的时候才走导出 PDF 这条路。

5. 常用设置项与个性化

5.1 如何把界面设置成中文

关于 MarkText 怎么设置中文，很多人在菜单里找不到入口。其实逻辑很简单：在菜单栏点击File -> Preferences，在弹出的设置窗口里找到General或者叫通用的选项区域，里面有一个Language下拉框，选择简体中文，然后重启应用即可生效。

需要说明的是，不同版本的 MarkText 中文语言包的完整度略有差异。部分版本在切换成中文后，菜单栏仍有极少数英文残留，这不影响使用。如果你下载的版本比较老，连 Language 下拉框都没有，建议直接去官网下载最新版本，不要浪费时间在老版本上做汉化补丁。另外，MarkText 的界面语言只影响界面，不会影响你现在文档里的内容，所以切换语言不用担心破坏文件。

5.2 主题与 Markdown 语法兼容性设置

MarkText 自带的主题有好几套，在设置里的Theme选项里可以切换。默认的浅色主题比较素雅，看久了不刺眼。如果你喜欢写代码时的那种深色背景，Dark主题也不错。我日常写作时用浅色，晚上整理博客时切到深色，配合打字机模式，长时间写也不会太累。

主题之外，MarkText 还提供了一些 Markdown 渲染细节上的开关。在设置页面里你可以决定是否自动识别GFM风格的自动链接文字、是否开启下划线强调、是否渲染数学公式、是否开启 emoji 快捷键等。我的建议是：如果你写的是技术文档，默认全开即可；如果写的是纯文本故事或者剧本，可以关掉自动链接识别，避免 URL 被自动转化成可点击的蓝色文字干扰排版。

5.3 侧边栏文件管理与跨平台同步

MarkText 支持直接打开一个文件夹作为工作区，侧边栏会展示文件夹里的文件树。在这个树状列表里，你可以新建文件、删除文件、重命名文件，也可以直接搜索文件内容。这里有个很实用的技巧：当你打开的是一个包含大量 Markdown 文件的博客仓库时，通过侧边栏顶部的搜索框输入关键词，MarkText 会对当前目录进行内容检索，直接定位到包含关键词的文档并高亮显示。写技术笔记时，这个功能比手动一层层翻文件夹高效得多。

跨平台同步方面，MarkText 本身就是纯本地文件编辑器，所以配合坚果云、OneDrive、或者 Git 仓库都可以实现同步。我最常用的方案是把这个工作区放到 Git 仓库里，写完后提交推送到远程，这样既有版本历史，又能在不同电脑之间保持内容一致。MarkText 不会锁文件，也不会产生私有数据库，所以它对版本管理工具非常友好。

6. 常见问题排查与避坑

6.1 Windows 下打不开或者白屏怎么办

如果安装完 MarkText 之后点击图标没反应，首先要区分是“完全没有窗口”还是“窗口白屏”。完全没窗口的，大概率是系统缺运行库，先把“Visual C++ Redistributable”装齐，装完重启电脑再试。如果出现白屏窗口，重点检查显卡驱动。Electron 应用在部分老电脑的集成显卡上会出现渲染失败，把显卡驱动更新到厂家提供的最新版本通常就能解决。

还有一种情况是配置文件损坏。可以尝试删除 MarkText 的配置目录，Windows 下通常在C:\Users\你的用户名\AppData\Roaming\marktext，删之前先备份，然后重新启动应用，它会自动生成一套新的配置。这个方法能解决大多数“莫名其妙”的设置类问题。

6.2 中文输入法有时无法正常输入

这是一个比较热门的问题，主要集中在微软拼音和部分第三方输入法下。表现是：输入中文时，候选框出现，但选择候选词后字符没有上屏，或者上屏以后又自动消失了。第一排查方向是切换输入法模式，比如把微软拼音切换到“英文模式”再切回中文模式。如果经常出现，就在 Windows 设置里把 MarkText 添加到兼容性程序的输入法兼容列表中，方法是在设置 -> 时间和语言 -> 语言 -> 微软拼音 -> 常规 -> 兼容性中开启“使用以前版本的输入法”。

这个问题本质上是 Electron 与 IME（输入法编辑器）的兼容性问题，不是 MarkText 单独的问题。换输入法、重装软件都没有用，最稳定的方案反而是升级 MarkText 版本，新版 Electron 对输入法的处理会好很多。

6.3 图片粘贴后路径不对

常见场景是：粘贴截图后，图片被自动放到了一个你不希望出现的目录里。MarkText 对图片复制路径的判断逻辑是：如果当前文档有文件名且已保存，默认在文档所在目录创建assets文件夹；如果文档还没保存过，它会把图片放到系统的临时目录。很多人第一次用的时候，文档还没保存就粘贴了一堆截图，结果几分钟后发现所有图片都跑到临时目录里去了，文档复制到别的地方后全部裂开。

解决办法很简单：新建文档之后，先Ctrl+S把文档保存在目标目录里，再去粘贴图片。这样图片路径就会以文档所在目录为基准生成。如果你已经不小心把图片粘到临时目录了，可以在编辑 -> 图片菜单里查看图片信息，手动把图片复制回文档目录，然后替换文档中的引用路径。

6.4 打开大文件或者长文档卡顿

MarkText 在渲染大文件时不像一些小而快的编辑器那么流畅。当文档超过几十个中文段落，且包含大量代码块和高亮时，光标移动和输入响应会变得迟钝。我实测过，一个约 300 行、包含大量代码块和多个表格的文档，在普通办公电脑上拖动滚动条时会出现轻微掉帧。

如果卡顿明显，可以暂时切到源代码模式编辑，这种模式下没有实时渲染负担，输入会流畅得多。改完再切回实时模式查看效果。另外，长文档也可以拆分成多个小文件，用侧边栏文件树统一管理，反而更有利于后期维护。这也是我最推荐的文档组织方式，不要尝试让 MarkText 去处理上千行的大文件。

7. 我个人的 MarkText 工作流与使用心得

说了这么多具体功能，最后聊一点我自己的使用习惯，给准备入坑的朋友一个参考。我现在的配置是：笔记本电脑上装最新版 MarkText，写作内容按项目分文件夹，每个文件夹里统一放一个assets子目录存图片，写完一篇文章后就整个目录推到 Git 仓库。MarkText 在这里的角色就是纯粹的内容生产工具，它不做知识管理，不做全库搜索，不参与任务计划，这些工作交给专门的软件去承担。

实际体验下来，MarkText 最打动我的不是某一个炫酷功能，而是“打开就能写”的利落感。它不弹窗、不引导、不打扰，输入流畅，渲染及时，对于需要长期和 Markdown 打交道的人来说，这种稳定安静的态度反而是最难得的。如果一个工具有很多高级功能但每次打开都要折腾半天配置，那它很难成为日常工具。

最后再说一个很小但很实用的技巧：如果你希望新建文档时就有一个固定的模板，可以把模板写好之后复制成新文件，再在文件树里重命名。MarkText 虽然没提供官方的“模板”入口，但这种方式用起来一点不麻烦。工具是死的，工作流是活的，找到适合自己的节奏，MarkText 就能真正成为你写作链路里跑得最顺的一环。