被文档工具折磨的你，需要喘口气-拓冰企业网站定制

你是否也有过这样的经历？

兴冲冲写了几十篇技术文档，想搭个团队知识库。
打开GitBook，一顿配置猛如虎，最后卡在编译报错上；
换用VuePress，光是搭环境就折腾一下午，改个错别字还得重新build。
明明是写文档，怎么搞得像在做工程部署？

说实话，我有时候就在想，能不能有个东西，写完Markdown往那一放，刷新下浏览器就能看？
不需要编译、不需要构建、甚至连命令行都不用开几次？

这就是我第一次遇到docsify时的感受——原来写文档可以这么轻。

🎯 本文能帮你解决什么

如果你也在找一款「开箱即用、维护省心、长得还不错」的文档工具，这篇文章就是为你准备的。

我会用最直白的方式，告诉你 docsify 好在哪、怎么装、怎么配，以及那几个我踩过的坑，帮你一天之内从零搭建出一个像样的文档站点。

👩‍💻我是爱折腾的一名程序媛，喜欢研究全栈开发的各种实践，热爱分享踩坑后的收获与思考，也享受用代码写出各种实用小工具解决问题的快乐。

如果你也在技术这条路上向前走，关注我，愿我们能彼此陪伴，一起成为更好的自己🌱

🧭 主要内容脉络

🔹 一个让人崩溃的文档维护故事

🔹 docsify 到底是什么，它和 GitBook、VuePress 有什么不一样

🔹 从安装到发布，一条龙实战步骤

🔹 那些配置最实用，哪些坑最容易踩

🔹 什么时候该选它，什么时候该换别的

💡 一个让人崩溃的文档维护故事

之前的项目文档库，大都是需要编译的框架。
Node 版本不对，编译报错；依赖装不上，又报错；好不容易 build 成功，部署上去发现样式丢了。

很多次真的想把电脑合上去喝杯奶茶冷静一下。

很多文档工具的定位越来越偏向「网站生成器」，功能是强大了，但写文档这件事本身的体验反而被忽视了。

docsify 的设计哲学不太一样——它不生成静态 HTML，而是运行时直接把 Markdown 转成网页。这意味着你不用编译，写完就能看。

是不是以为这样性能会很差？其实还好，现代浏览器解析那点 JS 根本不算事儿，首屏加载体验完全够用。

🛠️ docsify 到底是个啥

打个生活化的比方：

GitBook 和 VuePress 像是你要装修房子，先画图纸、买材料、施工、验收，最后才能住进去。

docsify 则更像是搭帐篷，把架子撑起来，东西往里一放，立刻就能用。

它的核心原理很简单：

🔹 你写一堆 Markdown 文件放在项目里

🔹 一个 HTML 入口文件引入 docsify 的 JS 和 CSS

🔹 用户访问时，JS 动态拉取对应的 Markdown 并渲染成网页

这里面有个关键的文件_sidebar.md，你只需要在里面列出文档标题和链接，侧边栏就自动生成了。
没有编译步骤，没有复杂的配置，改完文档提交代码就完事。

🚀 一条龙实战步骤

好，咱们直接动手。全程只需要三步，比泡一碗泡面还省事。

📦 第一步：全局安装 docsify-cli

npm i docsify-cli -g

装完后，你就能用docsify命令了。这里有一点要特别注意，如果你公司网络不好，npm 装全局包容易卡住，记得提前切好镜像源，不然第一关就劝退了。

🏗️ 第二步：初始化项目

docsify init ./docs

这个命令会在docs目录下生成三个文件：

🔹index.html—— 入口文件，整个站点就靠它

🔹README.md—— 首页内容，你想展示啥就写啥

🔹.nojekyll—— 防止 GitHub Pages 忽略下划线开头的文件

接下来重点来了，你需要在index.html里加一个配置，开启侧边栏功能：

window.$docsify = {

loadSidebar: true,

subMaxLevel: 2

}

</script>

然后新建一个_sidebar.md，里面写上你的文档目录结构。比如：

- [首页](/)

- [快速上手](quickstart.md)

- [API 文档](api.md)

- [用户模块](api-user.md)

- [订单模块](api-order.md)

保存，刷新浏览器，侧边栏就出来了。就这么简单。

👀 第三步：本地预览

docsify serve docs

打开http://localhost:3000，你的文档网站就活生生摆在那了。改一个字保存，浏览器自动刷新，体验丝滑。

有一点提醒一下：

就是如果你没装node环境，或者不想安装模块，也可以很简单：

上面的命令行工具做的事，其实就是帮你生成那三个文件，我们自己手动建就好了，index.html里面把css和js引入进来

还有一个就是拉起服务这块，测试的时候直接用VS Code里的Live Server就好，线上就Nginx或IIS了，
再不行就用python -m http.server 3000也一样能起服务

⚠️ 常用配置与容易翻车的点

再说几个我实际项目里觉得最实用的配置。

侧边栏折叠

如果文档层级深，建议开启折叠，不然侧边栏长得能拉好几屏。