开源项目要文档、公司要内部手册、团队要 API 说明——"文档站"是最适合静态化的场景：写完构建、扔 Nginx、配 CDN，速度和安全性都是动态网站比不了的。这篇对比三个主流方案，各给一套可抄的部署流程。

一、三方案对比

选型建议：

• 就想写完直接发布、别折腾 → MkDocs + Material 主题（颜值和功能的天花板）
• 要品牌定制、嵌入自定义组件 → VuePress
• 零构建、扔静态空间就能跑 → Docsify

二、方案一：MkDocs + Material（最推荐）

1. 安装：

pip install mkdocs-material
mkdocs new my-docs && cd my-docs

2. 目录结构：

my-docs/
├── mkdocs.yml          ← 全部配置：导航、主题、搜索、插件
└── docs/
    ├── index.md        ← 首页
    ├── getting-started.md
    └── api/
        └── reference.md

3. mkdocs.yml 核心配置：

site_name: 产品文档中心
theme:
  name: material
  language: zh
  features:
    - navigation.tabs      # 顶部标签导航
    - search.suggest       # 搜索建议
    - content.code.copy    # 代码块一键复制
nav:
  - 首页: index.md
  - 快速开始: getting-started.md
  - API 参考: api/reference.md

4. 本地预览 + 构建：

mkdocs serve          # 本地 http://127.0.0.1:8000 实时预览
mkdocs build          # 生成 site/ 目录，纯静态文件

5. 部署：site/ 目录整个扔到 Nginx 就行：

server {
    listen 443 ssl;
    server_name docs.yourdomain.com;
    root /www/wwwroot/docs-site;
    index index.html;

    location / {
        try_files $uri $uri/ /404.html;
    }
}

静态站部署通用流程见静态网站部署与 CDN 加速。

三、方案二：VuePress（要定制化选它）

npm init vuepress-theme-hope docs      # 或 npm create vuepress
cd docs && npm install
npm run docs:dev                       # 本地预览
npm run docs:build                     # 输出 dist/

VuePress 的优势是能写 Vue 组件——交互式 API 演示、自定义提示框、品牌头图，都能做进 Markdown。代价是构建吃内存（Node 构建时 2G 起步），且要有基本的前端工程概念。

四、方案三：Docsify（零构建）

Docsify 连构建都不要，index.html 引一个 CDN 脚本，Markdown 文件放旁边，完事：

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
  <div id="app">加载中…</div>
  <script>
    window.$docsify = {
      name: '产品文档',
      repo: '',
      loadSidebar: true,
      subMaxLevel: 3,
      search: 'auto'
    }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

注意：CDN 脚本在国内访问不稳定，建议把 docsify 的 JS/CSS 下载到自己服务器。 Docsify 适合"今晚就要上线"的场景，长期大量文档还是构建型方案（SEO 更好、首屏更快）。

五、文档站的通用功课

SEO：静态文档站是搜索引擎最友好的形态，但配置要对——每个页面独立 title、配 sitemap.xml、提交收录，方法见网站 SEO 基础优化指南。

速度：静态站 + CDN 是绝配，全球访问都快，见CDN 加速配置实战。

版本管理：文档目录放 Git，改动走 review，历史可追溯，见Git 版本控制与服务器部署。多版本文档（v1/v2 并存）用 MkDocs 的 mike 插件管理。

CI 自动构建（进阶）：Git 推送 → CI 跑 mkdocs build → 自动部署到服务器，写文档的人不用管构建。思路见Docker 镜像仓库与 CI 自动构建，换成 rsync 部署即可。

内网文档：内部手册不想公网暴露？同机部署 + 防火墙只放行办公网 IP，见服务器端口安全：最小化开放。

结语

文档站是自托管里最省心的一类：纯静态、无数据库、无安全补丁要追、构建一次用一年。选 MkDocs 还是 VuePress，只取决于你要不要定制——其他都是小事。

需要搭文档站服务器，可以看看财富云计算：NAT 型云服务器支持 443 映射，静态文档站 1核1G 都跑得飞快，配 CDN 回源后带宽也省，价格比独立 IP 机型省一半以上——文档这种"要 HTTPS 但不需要独立 IP"的场景，刚好对症。

延伸阅读

1. 网站环境怎么选：LNMP 手动 / 宝塔面板 / Docker / 云开发
2. 问卷表单系统搭建：SurveyKing / Formbricks，数据自己收
3. 图床搭建：Lsky Pro / Lychee，自托管图片托管方案
4. 邮件列表搭建：listmonk 自托管 Newsletter，把读者握在自己手里
5. RSS 阅读器搭建：FreshRSS 自托管，把信息流拿回自己手里
6. 短链接服务搭建：Shlink 自托管，链接数据自己掌握
7. 网站状态监控页搭建：Uptime Kuma，服务器挂了第一时间知道
8. 自托管密码管理：Vaultwarden 部署实战，把全家的密码管起来

更多阅读

1. 上一篇：RSS 阅读器搭建：FreshRSS 自托管，把信息流拿回自己手里
2. 下一篇：邮件列表搭建：listmonk 自托管 Newsletter，把读者握在自己手里