企业官网建设流程全解析

最近在给某个模拟项目整理开源文档的时候，我把原来的文档站整个迁移到了 docsify，折腾了两个晚上，连目录带内容全部理干净了。说实话，docsify 这个名字在开源文档圈子里已经不算新鲜，但真正把它用顺手之后，那种“改完 Markdown 刷新浏览器就生效”的流畅感，确实比传统的静态站点生成器舒服太多。

docsify 解决的是一个很实际的问题：写文档的人只想专心写 Markdown，不想改一句话就重新构建、打包、部署。它的核心思路是运行时解析——文档还是那些 Markdown 文件，访问站点的时候浏览器临时把它们解析成页面内容。这意味着你不需要预编译，不需要 node 脚本生成一堆 HTML，只要维护好文档源文件，一切都能同步更新。

如果你正在维护一个开源项目，或者正准备给自己的工具库写说明书，这篇文章应该能帮你少走弯路。我会把为什么选 docsify、怎么初始化、怎么配出好用的目录结构、怎么部署上线、以及我在实操里踩过的坑，一条一条掰开讲清楚。

1. 为什么是 docsify：先想清楚文档站的需要

1.1 开源文档的维护痛点与 docsify 的解法

我参与过几个开源项目的文档维护，最深的感受是：文档的“新鲜度”比“华丽度”重要得多。用户看文档的时候，最反感的就是版本号写着 2.x，接口说明却还停在 1.x。这背后的问题往往是——改一次文档的成本太高了。

传统静态站点生成器的工作流大概是：写 Markdown → 运行构建脚本 → 生成 HTML → 把 HTML 部署到服务器。每次改一个错别字，都要把这一套流程重新走一遍。如果你同时还维护着多个分支、多套版本的文档，构建成本还会叠加。哪怕只是修一行文字，也得等流水线跑完，才能在线上看到结果。

docsify 把这个流程简化成了：改 Markdown → 刷新浏览器。因为它是在浏览器端实时解析 Markdown 并渲染成页面的，服务端只需要提供静态文件即可。这个思路很像很多当下的前端轻应用——把渲染工作交给客户端，服务端只负责喂数据。

这个设计带来一个额外好处：文档仓库保持得非常干净，里面几乎只有.md文件和一些配置文件，不会出现几百个自动生成的index.html。你在仓库里随便搜一个词，搜到的永远是真正的文档内容，而不是构建产物。这对长期维护来说是决定性的优势。

1.2 和常规静态站点生成器的差异对比

我知道很多人在选型时会拿 docsify 和 VuePress、Docusaurus这批工具进行对比。它们不是一个物种，但经常被放在同一个篮子里挑选。用一张表来看差异会清晰很多：

这个对比想说明一件事：如果你做的是“产品说明书”式的软件文档，docsify 的弱点几乎都是无关紧要的。SEO 对软件文档来说，通常不如“内容准确、搜索方便”重要。而“改完立即生效”对频繁更新的文档来说，是实打实的效率提升。

我见过不少项目把文档和官网放在同一个站里，结果每次改文档都要重新构建整个站点。不是不行，而是没必要。文档部分完全可以独立出来，用 docsify 单独跑一套，维护成本立刻降下来。

1.3 什么样的项目适合用 docsify

docsify 不是万能的，如果遇到页面本身需要大量交互、需要后端渲染、需要精确的 SEO 投放，它就不太合适。但从我的经验看，它有很明确的最佳适用区间：

• 开源项目的 README 进阶版，希望有一个多页面、可搜索的文档站。
• 内部团队的组件库或工具库文档，重点是接口说明、示例代码和变更记录。
• 个人知识库或学习笔记，需要目录、搜索、多页签的展示方式。
• 项目原型阶段的临时文档，随时可能大改，不需要在构建上投入太多成本。

判断标准可以很朴素：如果你的文档内容大于站点效果，也就是“写什么”比“长什么样”重要，那 docsify 大概率适合你。反过来，如果网站视觉效果、交互体验、搜索引擎收录是第一位，那就老老实实用生成器。

2. 从零搭一个 docsify 文档站

2.1 三条命令完成初始化

先交代一下环境：docsify 是 Node.js 生态的工具，所以机器上需要有 Node.js 运行时和 npm 包管理器。版本只要不太老就行，官方建议 Node.js 12 以上，我用过的几个版本都没有踩到兼容问题。

安装 docsify 的命令行工具是全局安装：

npm i -g docsify-cli

装完之后，只需要两条命令就能起来一个站点。我习惯在一个项目目录下建一个单独的docs文件夹，专门放文档：

docsify init ./docs docsify serve ./docs

第一条命令会生成 docs 目录并在里面放好三个基础文件：index.html、README.md、_sidebar.md。第二条命令会启动一个本地预览服务，默认地址是http://localhost:3000。浏览器打开这个地址，就能看到文档首页了。

这一步值得多说一句：docsify 的服务只是轻量静态文件服务，正式部署时不会用它。它存在的意义是提供一个和线上环境高度一致的本地预览，让你改完内容之后第一时间看到效果。

2.2 目录结构里每个文件是干什么的

初始化完成后，目录看起来是这个样子：

docs/ ├── index.html ├── README.md └── _sidebar.md

index.html是整套 docsify 应用的入口。docsify 本质上是一个单页应用，所有页面请求都会回到这个文件，由它加载 docsify 的脚本、样式，并根据 URL 中的 hash 去加载对应的 Markdown 文件。

README.md是文档站的首页内容。docsify 默认把README.md当作站点的根页面。你写的所有其他文档也都放在同一个目录下，通过侧边栏的链接跳转访问。

_sidebar.md是侧边栏配置文件。它本身也是 Markdown 语法，写的是链接列表。docsify 会读取这个文件的内容，渲染成左侧的目录树。后续继续扩张文档时，最常见的操作就是往这个文件里加新的链接行。

这个结构在前期会让人产生“就这？”的错觉，但整套系统的灵活度全在index.html的配置项和插件机制里，后面我会逐个展开讲。

2.3 本地预览与实时刷新体验

文档服务启动之后，你会注意到一个细节：你不用保存一个文件就重启一次服务。docsify 自带监听机制，Markdown 文件一旦被修改并保存，浏览器里会自动刷新。这个体验其实就是开发环境下热更新的简化版，只不过 docsify 连编译这步都省了。

我第一次用的时候还不太相信，特意在一个很长的接口文档里删掉一句描述，切回浏览器，页面已经更新了。那一刻我觉得“写文档”这件事，第一次可以从任务变成纯粹的写作过程。

这里给一个非常实用的经验：本地预览跑起来之后，如果你改了_sidebar.md或index.html，不要把浏览器标签页一直挂着不动。偶尔手动刷新一次，能避免某些旧状态干扰判断。虽然 docsify 会热更新，但配置文件层面的改动偶尔会表现得不够即时。

3. 让文档站真正好用：核心配置与定制

3.1 index.html 里最常用的一批配置项

docsify 的index.html非常精简，基础结构通常是这样的：

<!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>项目文档</title> <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"> </head> <body> <div id="app">加载中...</div> <script> window.$docsify = { name: '项目名称', repo: '', loadSidebar: true, subMaxLevel: 3, search: 'auto', maxAge: 86400000 }; </script> <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script> <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script> </body> </html>

这里解释几个我每次都会用到的配置项，以及背后的考虑：

name配置项会显示在侧边栏顶部，相当于文档站的名字。我一般建议写成项目名而不是“文档中心”这种泛称，这样用户在侧边栏就能确认自己身处在哪个项目里。

repo配置的是代码仓库地址。配置之后，页面右上角会生成一个仓库链接入口。docsify 这么做很聪明，它把“查看源码”和“编辑文档”的隐性需求，直接变成了一套自动配置。无论是 GitHub 还是其他支持公开仓库的平台，都可以填完整地址或组织名加仓库名的格式。

loadSidebar: true用来开启侧边栏加载，这也意味着我们前面提到的_sidebar.md会被解析生效。有人会奇怪为什么这不算默认开启——因为不是所有文档站都需要侧边栏，比如一个只有单页文档的小工具，侧边栏反而是噪音。

subMaxLevel控制的是侧边栏自动展开标题的层级。比如设为 3，则自动展示 Markdown 里的一级到三级标题。这个配置让你的接口文档可以只写正文，不需要手动维护标题链接，docsify 会自动把标题提出来放进侧边栏。我通常设置成 2 或 3。太浅了目录信息不够，太深了侧边栏会像蜘蛛网一样复杂。

search开启全文搜索。配置为'auto'会让 docsify 自动为所有页面生成索引，并提供一个搜索输入框。对于一个动辄几十篇文档的项目来说，没有搜索的文档站基本等于半成品。

3.2 侧边栏和导航栏的目录维护技巧

_sidebar.md是文档站的灵魂，它的写法很简单，就是一个 Markdown 列表：

- [首页](/) - [快速开始](quickstart) - [核心概念](concepts/) - [模块 A](concepts/module-a) - [模块 B](concepts/module-b) - [API 参考](api/) - [常见问题](faq)

这里有几个细节需要特别注意。

链接的基准路径是docs目录，而不是域名根路径。写完链接后，一定确保目标.md文件真的存在于那个位置。我踩过一次坑，写链接时少了一层目录，侧边栏显示正常，但点击跳转后显示空白页，排查了半天才发现是路径问题。

docsify 对空目录和索引文件有自己的处理方式。如果某个目录下有一个README.md，那么点击链接可以只写目录路径，不写文件名。比如concepts/会自动关联concepts/README.md。这个能力适合给每个章节建一个子目录，各章节内容独立隔离，也方便按模块交给不同的人维护。

导航栏由_navbar.md控制，它是页面顶部的横向菜单。我一般只放几种链接：文档全览、Git 仓库地址、更新日志、以及一些站外资源。导航栏配置过多会导致顶栏拥挤，反而不利于阅读。

还有一个小技巧：侧边栏的层级和文档目录的物理结构，最好保持一致。这样做不只是为了让链接更直观，更主要的原因是维护成本——三个月后再回来改文档，你不会想面对一套链接逻辑和目录结构完全脱节的烂摊子。

3.3 封面、首页与多语言的支持方式

很多项目希望文档站在进入目录之前，先有一个展示项目定位的封面页。docsify 支持这个场景，只需要在配置里加上coverpage: true，然后创建_coverpage.md文件。

# 模拟项目 X > 一个解决 XX 问题的轻量级工具库 - 开箱即用 - 零依赖 - MIT 许可证 [开始阅读](#首页)

封面页的内容要克制，不要让用户滑半天才能看到真正的文档入口。标题、一句话简介、两三个特性关键词，以及一个明确的入口链接，足够了。文档站的首要任务是让用户快速进入文档，而不是在封面上做过多的品牌展示。

首页README.md的内容格式也很重要，它通常是一个项目的“第一印象”。我习惯的首页结构是：

• 一行项目简介。
• 一张运行效果图或示意代码。
• 几个高频问题的直达链接。
• 安装和快速使用的代码块。
• 指向完整文档的引导入口。

多语言支持是 docsify 另一个很自然的扩展点。它可以把语言切换器集成到顶栏，每个语言对应一套 Markdown 文件路径，例如zh/README.md和en/README.md。不过我实际观察下来，大部分开源项目在前中期根本不需要多语言，与其一上来铺两套文档，不如先把主语言的内容写透，等社区有一定规模后，再考虑补其他语言的翻译。

3.4 插件接入与按需选择

docsify 的插件体系是我认为它最被低估的地方。官方提供了一批高频插件，每个插件通常就是在index.html里加一个<script>标签，然后在配置对象里补一个开关。

比如代码高亮，docsify 默认支持一定的代码着色，但如果你的文档以代码片段为主，我强烈建议接入：

<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/prismjs/components/prism-bash.min.js"></script> <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/prismjs/components/prism-java.min.js"></script>

Prism 按语言拆分组件，你可以只加载文档中涉及的语言。这比一次性加载所有语言的方案更高效，页面加载速度不拖后腿。我通常在项目里提前确认文档涉及的代码语言，再加对应的组件。

还有几个值得常驻的插件：图片缩放插件可以让点击大图时自动放大预览；复制代码插件能给代码块加上一键复制按钮；emoji 插件可以支持在 Markdown 里直接写 emoji 短代码（如果你文档风格偏轻松）。注意：图片缩放对文档类站点几乎算刚需，尤其是那些包含架构图、运行截图的文档，没有放大能力，用户看细节会非常痛苦。

插件选择上我的原则是：先跑通主流程，再加体验增强项。不要第一次配置就塞十几个插件，出了问题你根本不知道是哪个环节引起的。

4. 实打实写一份开源文档：从结构规划到上线

4.1 先给读者画像，再定文档骨架

很多人写文档，打开编辑器就开始写细节，写出一个像脑图一样的文档，读者根本找不到入口。我现在的习惯是，动手之前先想清楚这个文档是写给谁看的。

一个典型的开源项目文档，读者画像可以分几类：

对应到侧边栏，就会形成一个相对固定的骨架：首页 → 快速开始 → 核心概念 → 手册 → API → 贡献 → FAQ。不同项目可以根据规模裁剪，这个骨架的顺序其实也遵循了一个心理逻辑：从“这是什么”到“我怎么用”再到“怎么参与开发”，逐步递进。

4.2 Markdown 写作规范与目录组织

文档的组织方式，直接影响维护效率。我推荐一个目录组织方式，按功能模块而不是按文件类型来分组：

docs/ ├── README.md ├── _sidebar.md ├── _navbar.md ├── _coverpage.md ├── quickstart.md ├── guides/ │ ├── README.md │ ├── installation.md │ ├── configuration.md │ └── deployment.md ├── api/ │ ├── README.md │ ├── core.md │ ├── cli.md │ └── events.md ├── contribute.md └── faq.md

每个子目录下的README.md，通常是一个引导页面，讲清楚这个模块的适用场景，然后通过链接引导到更深入的文章。这避免了单篇 Markdown 膨胀成几千行——一旦超过一千行，阅读体验和检索体验会同时下降，读者打开之后只看到一片文字海洋，很难定位到自己想要的内容。

写作的时候，我会强制自己遵守几条简单的规则：每篇文档开头必须有“这段文档讲什么”的属性；接口说明必须包含参数表；代码示例必须可以直接复制运行；凡是涉及到时间或版本号的信息，宁可写“当前版本”也不要写死一个具体日期。这些规则看起来琐碎，但它们决定了文档能不能经受住一年后的审视。

标题层级也要克制，我见过有人把##和####交叉用，渲染出来侧边栏层级逻辑混乱。docsify 的subMaxLevel配置虽然能自动提取标题，但如果文章本身的标题层级乱，提取出来的目录照样乱。一篇文档里，##作为章节级标题，###作为小节级标题，最多到####，再往下就应该拆成独立页面，而不是继续缩进。

4.3 部署：把文档推到静态托管平台

写好的文档站本质上是一堆静态文件，部署到任何静态托管平台都可以。步骤一般是：把 docs 目录（或整个项目仓库）推送到代码托管平台的远端仓库，然后在平台的 Pages 服务里选择源分支和源目录，保存之后平台会在每次推送时自动构建并发布站点。

配置时需要注意几个点：

第一，Pages 服务选择的源目录必须是 docs 目录所在的位置。如果你的仓库根目录下就是文档站，那选择根目录即可；如果文档站单独放在 docs 目录下，就选择 docs。选错了会直接导致页面打不开。

第二，如果站点部署在子路径下，比如https://some-domain.com/my-project/，你需要告诉 docsify 基础路径是什么。docsify 的basePath配置就是干这个的，不配置的话，资源文件路径会找错，样式和脚本全部加载失败。

第三，自定义域名时，记得所有资源路径尽量保持相对路径或按实际情况配置。文档站的内部链接用相对路径会更安全，因为不管挂在哪个域名或子路径下，只要目录结构一致，链接都不会失效。

部署完成之后，我习惯做一次跨环境验证：换个设备、清空缓存、直接访问部署后的域名，把首页、侧边栏每个链接点一遍，最后用搜索框搜几个关键词。这能一次性暴露绝大多数部署阶段的问题。

4.4 长期维护中值得坚持的习惯

上线只是文档维护的开始。真正决定文档质量的是后续一次又一次的增量更新。在这方面，我总结出几个值得坚持的习惯：

每次提交代码时，如果涉及接口变化、行为变化、配置项变化，必须同时更新对应的文档页面。可以把这个要求写进代码评审清单，缺少文档更新的提交原则上不通过。这可能有点严格，但它是防止文档腐烂最有效的一道闸门。

给文档页面加上最后更新时间和修改记录的模板。docsify 本身不强调这一点，但 Markdown 内容里可以留一个区块记录重要变更。读者看到时间戳，才知道这篇文档对应的是不是当前版本。

定期做文档的“垃圾清理”：把已经失效的示例代码删掉，把重复的说明合并，把孤立的页面移动到合适的位置。我一般会在每个版本发布前做一次小清理，发现侧边栏里超过三层的目录，就该考虑重构文章结构了。

还有一个容易被忽略的习惯：及时关注 docsify 版本更新。它升级基本平滑，但插件和主题的兼容性偶尔会变。每年集中升级一次，跑一遍本地预览，确认没有异常，再让线上站点也升上去。这个节奏不折腾，也能避免因为版本过老错过一些体验提升。

5. 常见问题排查与避坑实录

5.1 侧边栏点不动或目录不显示

这个问题到现在我也偶尔会遇到，最常见的原因是_sidebar.md文件命名错误或位置不对。docsify 要求文件名必须以_开头，而且必须放在 docs 根目录，不是放在任意子目录。如果文件名写成了sidebar.md，配置里开了loadSidebar也没有用，侧边栏只会是一片空白。

链接写错也是高发问题。比如文档实际路径是guides/installation.md，链接写成了/installation，页面会尝试加载根目录下的installation.md，自然失败。排查方式很简单：浏览器开发者工具里看网络请求，找到 404 的文件路径，就能倒推是哪一行链接写错了。

还有一个小细节：如果_sidebar.md里的层级是用 Tab 键缩进的，渲染会完全乱掉。Markdown 的列表缩进对空格和 Tab 的混用非常敏感，建议统一用空格缩进。

5.2 图片和资源路径加载失败

图片加载失败通常都是路径基准问题。docsify 渲染页面时，会基于当前 URL 的路径去解析相对路径。如果你的图片引用写成![图](./images/a.png)，这个路径是相对于当前文档所在目录的，而不是相对于根目录。文档和图片不在同一个目录时，最简单的做法是使用/images/a.png这样的根路径引用。

但这里又涉及另一个问题：如果部署在子路径下，根路径会被识别成域名根目录，而不是站点根目录。所以最稳妥的方案是使用 docsify 的basePath配合相对路径，或者干脆把图片统一放到一个 assets 目录下，从根路径引用。

我自己的习惯是收缩图片目录：整个文档站只保留一个assets目录，所有图片按功能模块分文件夹存放。这样做的好处有两个，一是路径结构一眼能看明白，二是做迁移或换目录时，只需要全局替换一次引用前缀。

5.3 搜索框搜不到新内容

docsify 的搜索插件在首次运行时会为每个页面建立索引，但如果你新增了一个 Markdown 文件，搜索不到是正常的，很可能是因为搜索索引没有更新。大多数情况下，强制刷新页面或者清一下浏览器缓存就能解决。

另外需要注意，搜索插件的索引字段默认只针对页面标题和正文的纯文本。如果你的文档内容大量依赖代码块，搜索命中率会不高。一个缓解办法是在文章开头用标题和描述性段落把关键术语写出来，这样既方便读者定位，也方便搜索插件抓取。

我还遇到过一种诡异情况：搜索框能出结果，但点进去后页面内容对不上。排查后发现，是有两个文档页面的标题完全一样，搜索插件的索引把它们合并了。所以标题别偷懒，既要准确还是要尽量唯一。

5.4 部署后刷新子页面变 404

这个问题和 docsify 本身关系不大，而是静态托管平台对“单页应用路由”的特殊处理。docsify 是 hash 路由，URL 形如/#/api/，刷新时服务器返回的其实还是根页面，理论上不该出现 404。

但如果你通过配置把 hash 路由改成 history 路由之后，深层子页面刷新时，服务器找不到对应的物理文件，就会返回 404。解决方式是要么回到 hash 路由，要么在平台侧配置一个 404 页面，让它返回index.html，再由 docsify 接管路由。

我建议文档站不要轻易用 history 路由。hash 模式虽然 URL 里多个#，看起来没那么干净，但零配置、兼容性最好，也不需要关心服务端转发规则。对文档站这种场景，稳定比美观重要。

5.5 一个排查问题的高效思路

整体说说我排查 docsify 问题时的大致顺序。第一步，把浏览器开发者工具打开，看网络面板里有没有红色请求；第二步，确认请求的路径是不是自己预期中的路径；第三步，回到index.html和_sidebar.md检查配置和链接；第四步，用一段最简单的 Markdown 新建一个页面，看是单页问题还是全局问题。

这个思路看起来很基础，但它能解决绝大多数问题——因为 docsify 本身的组件结构并不复杂，出错多数出在路径、配置和文件命名上。不要一上来就怀疑框架出了问题，八成是自己哪根路径写岔了。

我个人在实际操作中的体会是，docsify 最讨喜的地方，是它把维护文档的摩擦降到了最低。以前我写文档总要提心吊胆想着“这个页面最终会是什么样”，现在完全不用，只需要考虑内容本身。如果你也在维护开源项目，强烈建议用一个下午把文档站换成这套方案，它会帮你省掉未来无数个改文档的烦心时刻。