企业官网建设流程全解析

1. 先聊聊：为什么我坚持用VS Code写Markdown

如果你经常写技术文档、记开发笔记，或者维护个人博客，Markdown一定不陌生。而编辑器这块，我前后换过不少工具——Typora、Obsidian、Notion都试过，最后真正稳定下来长期使用的，反而是VS Code。原因很简单：它原生支持Markdown，而且不是那种“能编辑、能预览”的敷衍支持，是真正把Markdown当成一等公民来对待。

很多人第一次打开VS Code写Markdown，可能只是觉得“哦，有个预览按钮”，但实际用久了会发现，这套原生能力覆盖了从写作、排版到导出的完整链路。更关键的是，VS Code本身是一个可无限扩展的编辑器，Markdown只是它的基础能力之一，你可以随时在这个基础上叠加各种插件，把它变成适合自己写作习惯的专属工具。

这篇文章我打算从原生功能、配置优化、高效写作技巧、常见问题这几个维度，把VS Code写Markdown这件事讲透。不管你是刚开始接触Markdown的新手，还是已经写了不少文档的老手，应该都能在里面找到一些之前没注意到的细节。我也尽量把实际操作中踩过的坑、试出来的经验写出来，方便你直接“抄作业”。

2. VS Code原生Markdown能力的完整拆解

2.1 原生不是“阉割版”，基础编辑体验足够扎实

先说结论：VS Code对Markdown的原生支持，绝对够用，而且是经过精心设计的。它不是一个看不了预览、只能打字的纯文本编辑器，而是从一开始就把Markdown的编辑体验做了一个完整的闭环。

首先，VS Code内置了Markdown语法高亮。这意味着你写#标题、**加粗**、- 列表的时候，不同元素会有不同的颜色和样式，一眼就能看出层级结构。相比纯文本编辑器里满屏都是黑色小字，这种可视化反馈能大幅提升写作效率。语法高亮不是简单的颜色区分，它会智能识别代码块、行内代码、链接、图片、引用块等不同节点，连表格里的对齐线都会标出来。

其次，VS Code原生支持Markdown预览。打开一个.md文件后，按快捷键Ctrl+Shift+V（Mac上是Cmd+Shift+V），就会在右侧打开一个实时预览窗口，你写的内容会立即渲染成最终的HTML效果。这个预览默认是同步滚动的——你在左边编辑到哪个位置，右边自动滚动到对应位置，两边是实时联动的。

这个预览细节做得很好。它的渲染引擎用的是markdown-it，和很多主流Markdown平台是同一个引擎，所以预览出来的效果基本上和你发到网上的效果是一致的。我印象最深的是它支持<details>折叠块、任务列表的复选框交互，甚至还能渲染数学公式（后面会专门讲）。

另外，VS Code原生支持图片的拖拽插入和粘贴。你只需要把图片文件拖进编辑区，VS Code会自动生成相对路径的Markdown图片语法，比如![](./images/xxx.png)。如果是从剪贴板粘贴图片，默认行为可能只是把图片文件保存到项目里，路径问题需要配合插件调整。这一点在第三章会仔细说。

2.2 智能感知与快捷操作：原生功能里的隐藏宝藏

除了高亮和预览，VS Code还为Markdown内置了一些“隐藏”的智能功能，很多人可能用了很久都没发现。

第一个是标题导航。当你在编辑一个很长的Markdown文档时，打开左侧的资源管理器，文件列表上方会有一个“Outline”（大纲）面板，它会自动解析你文档里的所有标题结构，形成一棵树。你可以点击树上的任意节点，直接跳转到文档对应位置。对于动不动几千行的长文档来说，这个功能简直是效率神器，不用手动滚动查找。

第二个是路径智能补全。在写图片或链接的时候，只要输入![或[，VS Code就会触发文件路径的自动补全，你可以从项目文件里选一个目标文件。这解决了手写图片路径容易出错的大问题，尤其是项目结构比较深的时候。

第三个是链接跳转。Ctrl+点击（Mac上是Cmd+点击）一个链接，如果这个链接指向的是项目内的另一个文件，VS Code会直接打开那个文件；如果是锚点链接如#标题，会跳转到文档内对应标题位置；如果是普通网页链接，会调用默认浏览器打开。这个功能让Markdown文档之间形成了一种“可点击的网状结构”，写文档的时候真的有种“链接即导航”的感觉。

第四个是代码块的语法检测。Markdown文档里嵌的代码块，VS Code会按语言类型做高亮。如果你写的是JavaScript，它甚至会在代码块内提供一部分语法检查和补全能力。对于技术文档来说，这意味着你文档里的示例代码和真实代码一样具备可读性，读者复制出去就能直接用。

最后还有工作区的多文件搜索与替换。你可以在整个项目里搜一条文本，快速定位哪个文档的哪一段写了这个内容，然后一键全局替换。配合Markdown文档维护时，批量更新链接、修改术语，这个功能是刚需。

2.3 原生预览的快捷键与组合技巧

VS Code给Markdown预览准备了好几组快捷键，很多人只记住了Ctrl+Shift+V，但其实还有别的：

• Ctrl+Shift+V：在右侧打开预览，边写边看。
• Ctrl+K V：先按Ctrl+K，再按V，预览会以独立标签页形式打开，适合需要更大预览空间的时候。
• Ctrl+K S：打开快捷键大全，但这不是Markdown专属，算是编辑器通用功能。

值得多说一句的是，预览窗口并不是一个“静态渲染结果”，它和编辑器之间是双向联动的。你可以把光标定位在编辑器中的某一行，预览窗口会同步高亮对应的内容块；反过来，你在预览窗口点击元素，编辑器也会把光标跳转到对应源码位置。这种双向定位对修改长文档特别有用，我经常在预览里检查排版，发现问题时直接点击定位回去改。

预览窗口的左上角还有一个下拉菜单，可以切换预览的渲染方式。默认是“Default”，如果你装了Markdown Preview Enhanced插件，这里会多出一些选项，比如滚动同步方式、是否显示目录等。原生状态下够用，但装了插件会有更多玩法，这在第三章聊。

3. 从原生到顺手：值得补上的配置与插件

3.1 基础配置：让原生体验更贴合习惯

虽然原生功能已经不错，但有些默认行为还是不够“顺手”。我这里分享几个我长期使用的settings.json配置片段，你可以按需复制到自己的配置里。

{ // Markdown预览字体大小 "markdown.preview.fontSize": 15, // 预览是否显示行号 "markdown.preview.lineNumbers": "off", // 编辑器内是否显示空白字符（空格、Tab） "editor.renderWhitespace": "none", // 自动保存 "files.autoSave": "onFocusChange", // 关闭编辑器的迷你地图，把空间留给代码 "editor.minimap.enabled": false, // 粘贴图片时自动生成相对路径 "markdown.copyFiles.destination": "${documentDirName}/images/${documentBaseName}/", }

这几项里，最值得解释的是markdown.copyFiles.destination。这个配置是VS Code内置的“复制文件”功能，当你把外部图片粘贴到Markdown文档中时，VS Code默认会把图片保存到当前文档所在目录下。如果你不设置，图片可能散落在项目各处。我自己喜欢把每个文档的图片统一放在文档名/images/的子目录里，这样打包文档、迁移项目都很干净。

另外，files.autoSave我设置成onFocusChange，意思是当光标离开当前文件、切换到其他文件时自动保存。写Markdown的时候经常忘记按Ctrl+S，开了自动保存之后，预览一直是实时渲染的，不怕丢失内容。

3.2 扩展推荐：面向不同写作场景的插件组合

VS Code的Markdown生态很丰富，但插件不是装得越多越好，装多了反而会拖慢启动速度、造成配置冲突。我建议按自己的场景来选，下面这套组合是我在不同项目中实测过的：

这里面我特别想展开说两个：markdownlint和Markdown Preview Enhanced。

markdownlint是一个基于规则集的检查工具，类似代码里的ESLint。它默认开启很多条规则，比如标题层级不能跳级、列表前面空行、行尾不要多余空格等。刚用的时候可能会觉得“哪来这么多提示”，但适应之后你会发现，它能在很大程度上保证多人协作时文档风格统一。比如团队约定所有标题从一级开始、列表统一用-不用*，加了规则后，成员写进去的内容会自动被检查。

Markdown Preview Enhanced（以下简称MPE）则是我强烈推荐的重型插件。它不仅把预览效果提升了一个档次，还能直接导出PDF、HTML、PNG甚至PPT风格的手稿；支持数学公式渲染（MathJax/KaTeX）、支持用mermaid画流程图（虽然我在本文不展开mermaid，但它能支持）、支持自定义CSS主题，还内置了目录TOC生成。如果你的Markdown文档最终需要提交给非技术同事阅读，或者要打印成PDF存档，MPE几乎是最好的免费方案。

3.3 定制预览样式：让你的Markdown看起来更高级

很多人写Markdown的时候，会觉得默认预览样式有点“素”——标题不够突出、代码块样式一般、间距偏窄。其实你不用把文档复制到别的工具里调整，只需要给预览窗口配一套自定义CSS，就能让所有.md文件渲染出你喜欢的风格。

方法不复杂：在settings.json里设置markdown.styles数组，填入本地或远程的CSS文件路径。

"markdown.styles": [ "https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown.css", "style/custom.css" ]

如果你没有现成的CSS，也可以从网上下载一些开源的Markdown样式，比如github-markdown-css，它会自动把你的预览页面变成GitHub风格的排版，代码块、表格、引用块的样式都会好看很多。更进一步，可以在项目目录里放一个custom.css，自己覆写标题颜色、边框、间距等细节。

我自己常用的做法是：远程引入github-markdown-css，本地放一个custom.css，在里面把body字体调成“等距更舒服的中文字体”，同时给表格加个hover效果。这套配置在公司内部分享文档的时候，观感非常好，几乎不需要再用Word调整格式。

4. 实操：从零搭建一个Markdown写作工作流

4.1 场景拆解：一篇技术博客是怎么在VS Code里完成的

理论说了一大堆，不如直接走一遍完整流程。我自己写技术博客的日常是这样的：打开VS Code，新建一个项目文件夹，里面放docs、images两个目录，然后新建一个post.md文件开始写。这个项目的结构大概长这样：

my-blog/ ├── docs/ │ ├── images/ │ │ ├── post-cover.png │ │ └── screenshot-01.png │ └── post.md └── style/ └── custom.css

写作的时候，我一般开着两个窗口：左边是编辑区，右边是Ctrl+Shift+V打开的预览窗口。边写边看效果，空格、空行、加粗、列表都能即时反馈。如果某个地方格式乱了，不用切到别的地方，直接在预览里点击跳回源码改。

写完之后，我还会做一次“文档体检”：

• 用markdownlint的提示检查有没有漏空行、标题层级乱跳。
• 用Word Count CJK看看字数，判断文章长度是否合适。
• 用Markdown All in One的“格式化表格”功能，把表格对齐统一一下。

最后如果需要发布到某个平台，我会把Markdown内容直接复制过去，或者先用Markdown Preview Enhanced导出成HTML，再复制HTML内容。如果平台支持Markdown导入，这一步几乎零成本。

4.2 表格、公式、代码块的实战写法

写作过程中最常见的三个复杂元素是表格、数学公式和代码块，我把它们单独拎出来讲讲。

Markdown表格的语法本身不复杂，但手工对齐会让人崩溃。比如：

| 工具 | 是否支持Markdown | 导出格式 | 备注 | | ---- | ---- | ---- | ---- | | VS Code | 支持 | HTML/PDF/图片 | 需要安装相关扩展 | | Typora | 支持 | HTML/PDF/Word | 老牌编辑器 | | Obsidian | 支持 | HTML/PDF | 双链笔记利器 |

写完这个表格后，如果你用了Markdown All in One，可以打开命令面板（Ctrl+Shift+P），运行“Format Document”或者“Markdown All in One: Format Table”，它会自动把表格里的空格对齐成等宽。这样在源码里看也是整整齐齐的，预览里更是正正方方。

数学公式方面，VS Code原生预览支持的公式能力有限。如果你写的是数学相关的文章，我建议安装Markdown Preview Enhanced，然后在文档里用$...$写行内公式、用$$...$$写块级公式。渲染时选择MathJax或KaTeX引擎。我一般选KaTeX，速度更快。比如：

质能方程可以用 $E=mc^2$ 表示，也可以用块级公式表示： $$ E = mc^2 $$

代码块的处理就更简单了。用三个反引号加上语言标识符，比如```python，VS Code会自动做语法高亮。如果你还想在代码块里显示文件名，可以用MPE插件支持的属性语法，但这属于进阶内容，默认的代码块语法已经足够。

4.3 导出与发布：一份Markdown多种用途

Markdown最大的优势之一就是“一次编写，多处发布”。这里我按不同目标场景，列出我常用的导出方案：

• 发布到博客平台：直接把Markdown源码复制到平台的Markdown编辑器里，比如掘金、CSDN、知乎都支持，简单粗暴。
• 发布到微信公众号：微信公众号不支持Markdown，我的做法是先用Markdown Preview Enhanced导出为HTML，再用浏览器的“复制为富文本”粘贴到公众号编辑器里。或者用一些在线转换工具。
• 打印/存档为PDF：在Markdown Preview Enhanced预览页里右键，选择“Chrome (Puppeteer) 导出为 PDF”或“Prince 导出为 PDF”，可以生成排版精美的PDF。MPE自带的导出选项非常成熟。
• 转成Word：这是很多办公场景的需求。我的办法是先导出HTML，再用Word打开HTML文件另存为docx，或者直接把文本复制进Word再做样式微调。如果你有更自动化的需求，可以研究一下Pandoc，它能直接把Markdown转成Word，但需要额外安装命令行工具。

这里顺便提醒一句：搜索结果里经常能看到“vs code下的markdown预览导出乱码”这类问题，大部分是因为导出PDF时没指定中文字体，或者CSS里没有设置UTF-8编码。我的经验是，导出PDF前，先确认预览界面文字显示正常，再检查系统是否安装了中文字体。如果乱码，可以尝试换用Prince导出方式，Prince对中文字体支持相对更好。

4.4 方便好用的“半自动”写作组合拳

除了手动写作，VS Code还能帮你把一部分重复动作变成半自动，这里介绍几个我个人每天都在用的小技巧。

技巧一：快速创建带日期的文档

我习惯把笔记文件名加上日期，比如2024-06-15-关于XX.md。每次新建文件时手打日期很麻烦，虽然可以用系统日期，但不够内嵌。我的做法是用VS Code的代码片段功能（Snippets），在Markdown文件里输入date，然后按Tab，自动插入今天的日期。当然这不是Markdown专属，但确实大幅减少了我写文档头部的机械劳动。

技巧二：把常用模板存成代码片段

经常写技术方案的人，可能每次都会有一个固定模板：标题、背景、方案、总结。这个模板完全可以做成Snippet，每次新建文件时输入几个字母，直接生成一大段框架。Snippet里支持占位符$1、$2，写完第一个位置按Tab跳到下一个。

技巧三：用任务清单管理文章进度

如果一篇文章很长，我习惯在文首放一个任务清单：

- [x] 搭好文档框架 - [ ] 写第一章 - [ ] 补充截图 - [ ] 校对排版

在预览里，这些复选框是真实可点击的，写一段就点一个，进度一目了然。这也是VS Code原生渲染支持的功能，不需要插件。

5. 常见问题与排查实录

5.1 安装插件时提示“EPERM: operation not permitted”

这个问题在Windows上特别常见。很多人第一次装插件时，VS Code会报错：Error: EPERM: operation not permitted，看起来像是权限不够或者文件被占用。我排查过几次，大部分原因是VS Code的插件安装目录权限问题，或者杀毒软件拦截了扩展目录的写入。

解决思路是按顺序试：

1. 以管理员身份运行VS Code，再安装插件。
2. 如果还不行，关闭杀毒软件的实时防护，再次安装。
3. 检查扩展目录%USERPROFILE%\.vscode\extensions是否被设置为只读，取消只读属性。
4. 实在不行，重装VS Code，注意不要装到C盘权限过紧的路径下，比如Program Files；可以装到用户目录或D盘。

这个问题和Markdown没有直接关系，但很多新手第一次装插件就卡在这里，容易误以为“VS Code坏了”，所以值得专门提一下。

5.2 预览乱码或样式错乱怎么办

Markdown预览乱码有两种常见情况。

第一种是文档内容本身就是乱码。这多半是因为文件编码问题。VS Code默认是UTF-8，但如果你打开的是一个GBK编码的文件，编辑器可能识别不了。解决方法是点击右下角的编码按钮，重新选择“通过编码重新打开”，选UTF-8即可。

第二种是预览时中文显示成方块或者乱码。这更多是字体问题。在Windows上，VS Code预览默认会使用系统中的中文字体，如果字体缺失，可以手动在settings.json里指定字体：

"markdown.preview.fontFamily": "'Microsoft YaHei', 'PingFang SC', sans-serif"

另外，如果你自定义过markdown.styles，也可能是CSS引入的资源路径不对，导致渲染异常。检查一下CSS文件是否存在于指定路径，或者远程链接是否可访问。

5.3 表格复制散架、粘贴图片路径不对

很多人写Markdown表格的时候，从其它工具复制一个表格过来，粘贴到VS Code后，表格语法可能不是Markdown格式，或者格式乱了没法渲染。我的经验是：

• 从Excel/CSV复制过来的数据，别直接粘贴。先在编辑区里按Ctrl+Shift+P，运行“Markdown All in One: Insert Table”，或者手动把数据粘到一个临时文件，再选择数据，用命令把它转成Markdown表格。
• 从网页复制表格，浏览器里表格一般是HTML格式，VS Code不会自动转成Markdown。需要先粘贴到一个支持“HTML转Markdown”的地方，再用转换结果。

图片粘贴路径的问题，前面提过，设置好markdown.copyFiles.destination之后，粘贴图片会自动存到指定目录，再插入相对路径引用。如果用的是第三方插件Paste Image，它有自己的配置项，可以设置图片保存路径，但要注意不要和VS Code原生的图片复制功能冲突，否则会出现“粘贴一次生成两张图”的情况。我的建议是二选一：如果你装了Paste Image，就把VS Code自带的markdown.copyFiles禁用，或者在Paste Image的配置里把路径设置成和原生一致，保持统一。

5.4 与周边工具联动时容易踩的坑

这几个月里，我注意到社区里很多人在研究VS Code与AI工具的联动，比如把本地大模型接入编辑器的聊天窗口，或者在Markdown文档里直接生成内容。这里面的坑主要是配置路径和环境变量。

以Ollama为例，如果你想在VS Code里通过某个AI插件调用本地模型，你需要在插件配置里指定Ollama的服务地址，通常是http://localhost:11434。第一次调用时，插件会去拉模型列表，如果一直超时，先检查本地的Ollama服务是否启动，再检查代理设置。另外，Windows下本地模型的显存占用要留意，连续生成内容时可能因为显存不足导致编辑器崩溃。

还有一个容易忽略的点：很多AI插件会把生成的Markdown内容直接插入到当前光标位置。如果你写文档时习惯把光标停在代码块内部，插入的内容可能被嵌套在代码块里，导致Markdown渲染异常。我建议使用这类插件时，先把光标移到文档外层再触发生成，或者在生成后再检查一遍格式。

5.5 常见问题速查表

为了你排查方便，我把上面提到的问题整理成一张速查表：

这些问题基本都是我或者身边朋友实际遇到过的。处理思路的核心是“先确认基础环境，再查插件配置”，不要一上来就重装编辑器，那样成本太高，而且很多时候重装并不能真正解决问题。

6. 适合进阶用户的“更野”玩法

6.1 用Markdown做幻灯片、报告和笔记体系

Markdown不只是写博客的工具，它还能做很多“办公室场景”里的事。比如你想做一个简洁的幻灯片，不需要打开PowerPoint，装好Markdown Preview Enhanced后，可以在一个Markdown文件里用---分页：

# 第一页标题 - 要点一 - 要点二 --- # 第二页标题 | A | B | | -- | -- | | 1 | 2 |

然后在预览窗口中点击右键，选择“Open in Browser”，再配合浏览器的全屏模式，或者直接导出为HTML/PDF/PPT，就能得到一套简单但不简陋的幻灯片。这个用法特别适合内部技术分享，省去了来回切换Word、PPT的时间。

做报告也一样。把项目进展、数据表格、代码示例全部写在Markdown里，统一排好版后导出PDF，整个文档的质感和Word写出来差不太多，但维护成本低得多。我有一次给客户写需求分析文档，全程用VS Code写Markdown，最后导出PDF，客户那边的反馈是“排版很清晰”。

笔记体系更是Markdown的强项。你可以用VS Code打开一个专门的笔记文件夹，里面按时间或主题创建多个.md文件，再用大纲面板快速切换。如果你想增加跳转关系，就用相对路径链接互相链接，形成一套自己的知识库。

6.2 把Markdown文件变成网站或内部知识库

如果你写了很多Markdown文档，想把这些文档发布成一个可供团队访问的小网站，其实不需要上复杂的CMS。我试过用docsify或VitePress这类静态网站生成器，它们天然支持把Markdown文件渲染成网站页面，而且配置非常简单，通常是装一个Node包、写一个配置文件，然后把Markdown文件放进指定目录即可。

这种方式的优势在于：你不需要把文档从一个工具复制到另一个工具，所有内容都维护在本地Markdown文件里，改完之后执行一遍构建命令（或者配置自动部署），团队成员就能在浏览器里看到最新版。这对团队内部的知识库、接口文档、运营手册特别实用。

如果你用的是VitePress，你还可以利用它支持Markdown扩展语法的能力，在文档里写自定义容器、代码组等，排版会更灵活。但核心还是Markdown本身，VS Code全程作为编辑器，配合预览和lint，生产效率非常高。

6.3 与本地大模型、代码生成类插件结合

2024年以来，AI辅助编码和写作工具变得非常流行，很多插件都能在VS Code里直接调用大模型生成Markdown内容。如果你想体验“在Markdown文档里让AI帮你起草段落”，可以考虑配置本地模型（比如Ollama）或者插上你习惯的AI服务。

我个人的建议是：不要把AI当成文档的唯一作者，而是当成一个“初稿生成器”。比如你要写一段关于某个接口使用的说明，可以先让AI生成一版Markdown草稿，然后手动校对、补充细节、调整格式。因为Markdown本身是纯文本，你完全可以把AI生成的内容复制到VS Code里逐段审阅，而不用打开任何额外工具。这个工作流我自己用下来，最大的收益是节省了“从空白页开始”的启动成本，而不是完全甩手。

不过要注意：AI生成的内容可能存在事实性错误，或者格式不规范。如果你把它直接发布到正式文档里，容易被人看出“机翻味太浓”。我的做法是至少在VS Code里跑一遍markdownlint，再通读一遍，把术语和风格统一成自己的。

7. 我对这套工作流的真实体会

写到这里，我想聊一点自己的感受。VS Code并不是一个纯粹的“Markdown编辑器”，它的定位是通用代码编辑器，但正因为它把Markdown原生支持做得扎实，反而让我这种喜欢折腾工具的人找到了一个稳定的落脚点。你不必为了Markdown单独安装一个软件，也不用在各个编辑器之间反复横跳。装好VS Code，配好插件，一个人的文档工作流基本就能跑通。

我日常的使用习惯是：电脑上的VS Code长期开着，随手新建一个.md文件就能开始记录，无论是会议纪要还是技术方案；写到中途发现需要插图，直接截图粘贴，路径自动归位；改完一轮，用预览看一眼排版，然后导出HTML或PDF发给同事。整个过程没有离开过这个编辑器。

当然，也会有人觉得VS Code默认配置不够好看、需要折腾CSS和插件，这个门槛确实存在。可换个角度想，这种可定制性也带来了别的编辑器给不了的灵活性。花一下午时间把环境调成自己顺手的样子，之后每一篇文章的产出都会受益。

最后再分享一个小技巧：如果你在团队里整理文档，记得把所有.md文件统一放到项目根目录下，图片统一放在images文件夹中，同时要求大家把文件编码固定为UTF-8。这样无论谁接手，打开VS Code都能直接预览，不会出现路径断裂或者字符乱码的问题。文档的整洁度和代码的整洁度一样重要，都是长期合作的润滑剂。