# Docsify

> 分类：`libs/docsite/` · 档位：**评估** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 4.x |
| License | MIT |
| 维护方 | docsify 社区 |
| 仓库 / 文档 | https://github.com/docsifyjs/docsify · https://docsify.js.org |
| 最近 release | 见官方 releases |

## 2. 一句话定位

零构建文档站：一个 `index.html` 加一堆 Markdown，浏览器里实时渲染成站点，支持侧边栏、搜索、代码高亮。
代价是内容由 JS 渲染，SEO 与首屏不如静态生成方案。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| 核心 `docsify.min.js` | 约 70 KB | 约 20 KB（估算，待实测） |
| 主题 / 插件 | 另计 | 按需引入 |

## 4. 核心 API

```html
<script>
  window.$docsify = {
    name: 'Web Techs',
    loadSidebar: true,
    subMaxLevel: 2,
    search: 'auto',
  };
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
```

```text
index.html
README.md        # 首页
_sidebar.md      # 侧边栏
libs/lenis.md    # 直接写 Markdown
```

## 5. 适用 / 不适用

- **适用**：内部文档、个人笔记、快速搭建的说明站、原型期知识库。
- **不适用**：SEO 要求高的公开文档、超大文档集（选 VitePress / Docusaurus / Astro）。

## 6. 硬缺口与已知坑

- 内容是运行时 JS 渲染，爬虫只看到空壳，SEO 天然吃亏。
- 首屏依赖 JS 与 Markdown 请求，弱网下白屏时间明显。
- 默认从 CDN 加载，内网或离线部署要把文件下载到本地。
- 大文档集没有预构建索引，搜索与路由性能会下降。
- 定制深度有限，复杂主题要改 CSS 或写插件。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建 | 可用 | 核心卖点，直接静态托管 |
| ESM / 打包器 | 可用 | 但通常没必要 |
| SSR | 不适用 | 浏览器端渲染 |
| 客户端重渲染 | 无关 | 只加载一次 |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 3 | 更新节奏放缓 |
| 版本与破坏性变更 | 4 | 4.x 长期稳定 |
| 采用度 | 3 | 常见于内部文档 |
| 体积与按需 | 4 | 约 20 KB，单文件 |
| 生态兼容 | 4 | 插件机制简单 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| VitePress | 静态生成、SEO 好、基于 Vite | 需要 Node 构建 | 公开技术文档 |
| Docusaurus | 插件与版本化文档完善 | React 体系、构建较重 | 多版本文档 |
| Astro + Starlight | 现代、默认零 JS、可扩展 | 需要构建 | 新项目文档 |
| 纯 GitHub README | 零成本 | 无导航与搜索 | 极简说明 |
