# 文档即网站：Docsify+cpolar让技术文档秒变在线服务
**技术团队最熟悉的场景：项目交付时，对方问“文档在哪儿”；你翻出压缩包，发过去，然后收到“解压密码是多少”。**
**更常见的场景**：README.md写了两千行，团队协作靠传文件，版本编号从`v1.0`排到`v1.0_final_最终版_真的不改了.docx`。
Docsify解决的是**“文档即网站”**的问题：**不需要编译、不需要生成HTML，一个README.md放在目录里，启动服务就变成可访问的站点**。而cpolar补上最后一块拼图：**让这个站点不锁在本地，能被任何地方的人打开**。
## 一、Docsify哲学：放弃构建，拥抱纯文本
传统技术文档工具（GitBook、VuePress、Hexo）的共同特征是**构建时生成**——修改文档后必须执行`build`命令，输出静态HTML，再部署到服务器。这个流程天然割裂了**“写”与“发”**。
Docsify反其道而行之：**它不生成HTML文件，而是在浏览器里动态加载Markdown，实时渲染**。
```bash
# 全局安装命令行工具
npm i docsify-cli -g
# 初始化文档目录
docsify init ./docs
# 启动本地服务（默认监听3000端口）
docsify serve docs
```
三条命令，得到一个结构：
```
docs/
├── index.html # 站点入口
├── README.md # 首页内容
└── .nojekyll # 阻止GitHub Pages忽略下划线开头文件
```
<"y0.p5k3.org.cn"><"e4.p5k3.org.cn"><"u6.p5k3.org.cn">
**这就是全貌**。后续所有文档工作：**写Markdown、保存、刷新浏览器**。没有构建过程，没有版本编译。文档与网站是同一个文件。
## 二、它凭什么承载企业级文档？
“没有构建”容易被误解为“只适合个人笔记”。但事实是：**华为云部分开源组件文档、阿里云开发者社区教程、MIT某课程实验手册**均使用或推荐过Docsify方案。
核心支撑能力来自**插件体系**：
```html
```
**一个index.html就能承载**：
- **侧边栏导航**（`_sidebar.md`）
- **全文搜索**（无需后端）
- **代码高亮**、**Emoji**、**数学公式**
- **Google Analytics/百度统计**集成
- **Gitalk/Vssue评论系统**
某SaaS公司产品经理反馈：**“以前用Confluence，写个接口文档要开三个浏览器标签；现在用Docsify，Markdown写完就是发布状态”**。
## 三、局域网服务：准备好了，但没人能看见
Docsify服务默认跑在`127.0.0.1:3000`。**这对个人写作足够，对团队协作远远不够**。
交付现场常见对话：
> 开发：我本地启动docsify了，你访问`localhost:3000`看看。
> 产品：打开是空白页。
> 开发：哦，你还没装Node和docsify。
**这是Docsify作为“协作工具”的最大断层**——**它解决了写文档和看文档的一致性，但没解决服务可达性**。要让非技术人员、非本机设备访问文档，需要一个公网入口。
## 四、cpolar：为本地文档装上网关
cpolar的介入逻辑极其简单：**把`127.0.0.1:3000`映射成一个`https://xxxx.cpolar.top`**。
**部署操作**：
1. **安装**（Windows/Mac/Linux均有对应包）
```bash
cpolar version # 验证安装
```
2. **启动隧道指向Docsify端口**
```bash
cpolar http 3000
```
<"g3.p5k3.org.cn"><"q7.p5k3.org.cn"><"x3.p5k3.org.cn">
3. **获取公网地址**
```
Tunnel Status online
Version 3.3.3
Web Interface http://localhost:4040
Forwarding https://docsify-2026.cpolar.top -> http://localhost:3000
```
**此时，任何人在任何网络下打开`https://docsify-2026.cpolar.top`，看到的就是本地README.md渲染的网站**。
**免费套餐**：随机域名，每24小时变化，适合短期协作；
**付费套餐**：固定二级子域名，支持自定义备案域名，可配置密码访问。
## 五、场景升维：文档成为基础设施
当“文档即网站”叠加上“内网穿透”，发生的变化不是线性而是阶跃的：
**场景A：项目交付即开即用**
交付团队到客户现场，打开笔记本启动docsify，cpolar生成一个`https://交付项目.cpolar.top`，客户现场所有人用手机扫码即可查看完整的部署手册、API文档、常见问题。**无需U盘拷贝，无需发邮件，无需帮每个人安装阅读器**。
**场景B：技术团队异地协作**
北京产品经理更新需求文档，上海开发刷新浏览器就看到最新版；深圳测试补充用例，广州运维直接复制文档里的shell命令。**所有人操作同一个URL，版本问题自动归零**。
**场景C：个人知识库随身携带**
博主在咖啡馆改博客草稿，保存后通过固定域名预览效果；通勤路上用平板审阅旧文章，随时修订错别字。**所有设备共享一个文档源，无需同步软件**。
## 六、两个常见堵点与处置
**堵点一：侧边栏不显示**
`_sidebar.md`文件需显式在`index.html`中声明：
```javascript
loadSidebar: true
```
同时注意文件名以下划线开头，部分Git GUI客户端可能忽略，提交前确认文件已纳入版本控制。
**堵点二：内网穿透域名被拦截**
部分企业内网防火墙屏蔽未备案域名。**解决方案**：购买备案域名，cpolar支持将隧道绑定至自定义域名，CNAME指向cpolar网关。
## 七、不必羡慕复杂，够用才是技术债的解药
技术文档的本质是**信息传递**。为了这个目标，业界发明了XML、DITA、DocBook、静态站点生成器……但最终，**99%的技术写作者只需要一个能力：写完Markdown，别人马上能看到**。
Docsify放弃构建，换来的是**零维护成本**；cpolar放弃公网IP，换来的是**零服务器成本**。两者的组合，让技术文档第一次实现了“写即发布，发即访问，访即同步”。
**当文档不再需要“部署”，技术债里最顽固的那一笔，就悄悄销账了**。