Docsify 搭建 Markdown 知识库：本地写文档，用 cpolar 临时分享给同事评审-迪斯科星球

Docsify 搭建 Markdown 知识库：本地写文档，用 cpolar 临时分享给同事评审

文档最怕两件事：一是散在聊天记录里，二是写完没人愿意看。我的做法很简单，把项目说明、接口约定、部署手册都放进一个 Markdown 目录，用 Docsify 本地预览，再用 cpolar 开一个临时 HTTPS 地址丢给同事评审。

这套方案不需要先买服务器，也不用为了半小时评审去配置一整套发布流水线。覆盖项目早期、内部评审、客户临时预览、移动端查看效果这几类场景。

1 什么是 Docsify？这篇里它负责把 Markdown 变成文档站

Docsify 是一个文档站生成工具，它和常见静态站生成器的区别在于：它不会提前把 Markdown 编译成一堆 HTML 文件，而是在浏览器里动态渲染 Markdown。

这篇教程里，我们只拿它做一件事：把本地docs目录变成一个可以搜索、有侧边栏、能在浏览器里看的知识库。

可以放进去的内容包括：

项目 README 和快速开始
接口说明、字段约定、错误码
部署手册、排错记录
团队规范、交接文档

别一上来就把它当成公司级知识平台。先从一个项目目录开始跑通，后面再决定要不要接 GitHub Pages、对象存储或者内部服务器。

2 环境准备：安装 Node.js、Docsify CLI 和 cpolar

这一节先把工具装好。Docsify 负责本地文档站，cpolar 负责把本机的3000端口临时映射成外网 HTTPS 地址。

2.1 检查 Node.js 和 npm

Docsify CLI 通过 npm 安装，所以本机要先有 Node.js。打开终端执行：

node -v npm -v

能看到版本号就继续。这里使用 Node.js LTS 版本更稳，后面团队成员复现时也更稳。

如果本机还没装 Node.js，可以去 Node.js 官网下载安装包，或者在 macOS 上用 Homebrew 安装：

brew install node

2.2 安装 docsify-cli

Docsify 官方快速开始采用全局安装docsify-cli，它用来初始化目录和本地预览。

npm i docsify-cli -g

装完后检查命令是否可用：

docsify -v

如果提示找不到docsify，先检查 npm 全局 bin 目录是否在PATH里。这个坑很常见，尤其是用 nvm 管 Node.js 的机器。

2.3 安装 cpolar

cpolar 这一步不是为了正式上线，而是为了临时评审。Docsify 默认跑在本机，办公室外的同事打不开；评审窗口期打开隧道，评审结束关闭隧道，节奏会轻很多。

macOS 可以用 Homebrew 安装：

brew tap probezy/core && brew install cpolar sudo cpolar service install sudo cpolar service start

Linux 可以使用官方一键脚本：

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash

安装后打开本地管理页面：

open http://127.0.0.1:9200

Linux 桌面环境没有open命令时，直接在浏览器访问http://127.0.0.1:9200。登录后 cpolar 会在本机建立账号绑定；纯命令行环境也可以用cpolar authtoken手动绑定。

3 初始化 Docsify：创建知识库目录

这里我用team-docs-demo做示例项目名。你可以换成自己的项目目录，但后面的命令要保持一致。

mkdir team-docs-demo cd team-docs-demo docsify init ./docs

初始化完成后，目录里会有这些文件：

tree -a docs

典型结构是：

docs ├── .nojekyll ├── README.md └── index.html

README.md是首页内容，index.html是 Docsify 的入口文件，.nojekyll用在 GitHub Pages 场景，保留即可。

先改一下首页内容，确认渲染链路正常：

cat > docs/README.md <<'EOF' # 团队知识库 这里记录项目文档、接口约定、部署步骤和排错经验。 ## 快速入口 - [接口说明](api.md) - [部署手册](deploy.md) - [排错记录](troubleshooting.md) EOF

再补三个页面：

cat > docs/api.md <<'EOF' # 接口说明 ## 用户列表 请求地址：`GET /api/users` 响应示例： ```json { "items": [], "total": 0 }

EOF

cat > docs/deploy.md <<'EOF'

部署手册

启动服务

npm install npm run build npm run start

EOF

cat > docs/troubleshooting.md <<'EOF'

排错记录

本地端口被占用

查看 3000 端口占用：

lsof -i :3000

EOF

这里别急着写一大堆文档。先放 3 个短页面，跑通侧边栏和搜索后，再迁移原来的 Markdown。 ## 4 配置侧边栏、导航和搜索 Docsify 的好用之处在于配置很轻。我们加一个侧边栏，再开启搜索插件，知识库就有了基本可用的阅读体验。 ### 4.1 添加侧边栏 创建 `_sidebar.md`： ```bash cat > docs/_sidebar.md <<'EOF' - 项目文档 - [首页](README.md) - [接口说明](api.md) - [部署手册](deploy.md) - [排错记录](troubleshooting.md) EOF

再修改docs/index.html，把loadSidebar和搜索配置加进去。可以直接覆盖成下面这个版本：

cat > docs/index.html <<'EOF' <!doctype html> <html> <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@5/dist/themes/core.min.css"> </head> <body> <div id="app">加载中...</div> <script> window.$docsify = { name: '团队知识库', repo: '', loadSidebar: true, subMaxLevel: 2, auto2top: true, search: { paths: 'auto', placeholder: '搜索文档', noData: '没有找到结果', depth: 3 } } </script> <script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script> <script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/search.min.js"></script> </body> </html> EOF

划重点：loadSidebar: true会让 Docsify 读取_sidebar.md，subMaxLevel: 2会把页面里的二级标题也展示出来。文档多起来以后，这两个配置比主题颜色更重要。

如果侧边栏没出来，优先检查文件名是不是_sidebar.md，下划线别漏；再检查当前访问路径是否在docs服务根目录下。

4.2 本地启动预览

在项目根目录执行：

docsify serve docs

终端会显示本地访问地址，默认是：

http://localhost:3000

打开浏览器访问http://localhost:3000，能看到首页、侧边栏和搜索框，就说明知识库已经跑起来了。

这一步不是为了截图好看，而是确认 Markdown 到浏览器的链路通了。后面你改README.md、api.md这些文件，浏览器刷新就能看到新内容。

5 用 cpolar 暴露本地 3000 端口，生成临时 HTTPS 地址

本地能看只是第一步。真正评审时，经常会遇到一个尴尬点：同事不在同一个网络，客户也无法访问你的localhost:3000。

这时候就用 cpolar 开一个 HTTP 隧道，把本地 Docsify 服务临时映射出去。

保持docsify serve docs运行，再开一个新的终端执行：

cpolar http 3000

命令运行后，终端会输出公网访问地址。你也可以打开 cpolar 管理页面查看：

http://127.0.0.1:9200

在“状态 / 在线隧道列表”里找到 HTTP 隧道，复制 HTTPS 地址发给同事。对方打开这个地址，看到的就是你本机正在运行的 Docsify 文档站。

免费随机地址用于临时演示，地址会在 24 小时内变化。评审、验收、移动端预览这类短窗口任务足够用了；如果团队要长期固定访问，再考虑固定二级子域名或正式部署方案。

这里有个安全提醒：不要把含密钥、生产数据库地址、客户隐私的文档放进临时评审站。Docsify 是文档展示工具，不负责替你做内容脱敏。

6 同事评审时怎么更新文档、排错和关闭隧道

评审时最舒服的流程是：你本地改 Markdown，同事刷新页面看结果。比起来回发压缩包，这种方式省很多沟通成本。

6.1 修改文档后刷新即可

比如你要改部署手册：

cat >> docs/deploy.md <<'EOF' ## 检查服务状态 ```bash curl http://127.0.0.1:3000

EOF

保存后让同事刷新 cpolar 的 HTTPS 地址。Docsify 会重新加载 Markdown 内容。 如果同事说页面没变，先让对方强制刷新浏览器；再确认你改的是 `docs` 目录下的文件，不是项目里另一个同名 Markdown。 ### 6.2 手机预览也要看一眼 Docsify 的页面在手机上也能阅读。把 cpolar 的 HTTPS 地址发到手机浏览器里，看首页、侧边栏、搜索框是否顺手。 这一步很实用。很多接口文档在电脑上看着清楚，到了手机上标题层级太深、表格太宽，评审时很快就暴露出来。 ### 6.3 评审结束后关闭 如果你是用命令行开的临时隧道，在运行 `cpolar http 3000` 的终端里按 `Ctrl + C` 即可关闭。 Docsify 本地服务也可以按 `Ctrl + C` 关闭。确认两个终端都停掉后，外部链接就不再提供这次预览。 如果使用 cpolar Web UI 创建了隧道，就到隧道列表里停止或删除对应隧道。这里别偷懒，临时评审链接用完就关，是很好的团队习惯。 ## 7 常见问题：这几个点最容易卡住 ### 7.1 端口 3000 被占用 Docsify 默认用 `3000`，如果端口被别的服务占了，可以指定其他端口： ```bash docsify serve docs -p 3001

对应的 cpolar 命令也要改成同一个端口：

cpolar http 3001

端口前后一致很关键。Docsify 跑在3001，cpolar 却映射3000，外部访问就会打开错误服务或直接失败。

7.2 图片路径显示不出来

Markdown 图片统一放在docs/assets/目录下，例如：

mkdir -p docs/assets

引用时使用相对路径：

![系统架构图](assets/architecture.png)

图片不显示时，先检查文件名大小写。macOS 本地不敏感，Linux 或部署环境里会卡得很明显。

7.3 搜索不到新页面

搜索插件会根据侧边栏和已访问页面建立索引。新页面加完后，记得把它写进_sidebar.md，再刷新页面。

如果搜索框没有出现，检查index.html里是否同时保留了search配置和search.min.js插件脚本。

7.4 cpolar 地址打不开

按这个顺序查：

本机http://localhost:3000是否能打开 Docsify
cpolar 管理页http://127.0.0.1:9200是否能打开
在线隧道列表里 HTTP 隧道是否在线
复制给同事的是 HTTPS 地址，不是本地地址

排错时别一上来重装。先确认本地服务通，再看隧道状态，能省不少时间。

8 总结

到这里，我们已经把一个普通 Markdown 目录做成了 Docsify 文档站：本地可以写、浏览器可以预览、侧边栏和搜索也能用；需要外部评审时，再用 cpolar 临时开放一个 HTTPS 地址给同事访问。

关键步骤就三件事：

用docsify init ./docs初始化文档目录，再用docsify serve docs本地预览。
配置_sidebar.md、loadSidebar和搜索插件，让知识库具备基本导航能力。
用cpolar http 3000暴露本地 Docsify 服务，评审结束后及时关闭隧道。

我把这套流程定位成“文档评审工作流”，而不是一套正式发布系统。它的优势在于轻：Markdown 继续放在项目里，评审链接按需打开，问题改完马上刷新。等文档稳定下来，再迁移到 GitHub Pages、内部服务器或团队知识平台，会顺手很多。

企业官网建设流程全解析