你是否也有过这样的经历兴冲冲写了几十篇技术文档想搭个团队知识库。打开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-clinpm i docsify-cli -g装完后你就能用docsify命令了。这里有一点要特别注意如果你公司网络不好npm 装全局包容易卡住记得提前切好镜像源不然第一关就劝退了。️ 第二步初始化项目docsify init ./docs这个命令会在docs目录下生成三个文件index.html—— 入口文件整个站点就靠它README.md—— 首页内容你想展示啥就写啥.nojekyll—— 防止 GitHub Pages 忽略下划线开头的文件接下来重点来了你需要在index.html里加一个配置开启侧边栏功能scriptwindow.$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也一样能起服务⚠️ 常用配置与容易翻车的点再说几个我实际项目里觉得最实用的配置。侧边栏折叠如果文档层级深建议开启折叠不然侧边栏长得能拉好几屏。scriptwindow.$docsify {loadSidebar: true,subMaxLevel: 2,sidebarDisplayLevel: 1}/script全文搜索docsify 内置了搜索插件只需加一行