Docsify + Nginx 部署指南：解决 404 路由与 Markdown 加载失败问题

摘要：使用 Docsify 构建文档站点轻量又高效，但在部署到 Nginx 时，常遇到"首页能打开，点击导航后内容 404"或"无法加载 README.md"等问题。本文深入剖析原因，并提供完整、可靠的 Nginx 配置方案与调试技巧。

一、为什么 Docsify 需要特殊 Nginx 配置？

Docsify 是一个基于前端路由的单页应用（SPA） ，它不生成静态 HTML，而是通过 JavaScript 动态加载 Markdown 文件并渲染页面。

这意味着：

用户访问 /guide/ 时，浏览器实际加载的是 index.html；
Docsify 在前端解析路由，并发起 AJAX 请求获取 /guide/README.md；
如果用户直接刷新页面 或从外部链接进入 /guide/，服务器必须仍返回 index.html，否则会 404。

这与传统静态站点（如 Hugo、Jekyll）完全不同------后者每个页面都有真实 HTML 文件。

二、典型问题现象

首页正常，点击导航后空白或 404
- 浏览器地址栏变为 /guide/，但页面无内容。
控制台报错：Failed to load resource: the server responded with a status of 404
- 通常是 README.md、_sidebar.md 等文件加载失败。
手动访问 .md 文件返回 404 或被拒绝

这些问题的根源往往在于 Nginx 配置未正确区分"前端路由"和"静态资源" 。

三、正确 Nginx 配置（关键！）

✅ 基础配置模板

ini 复制代码

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/docs;  # 指向包含 index.html 的目录
    index index.html;

    # 允许 .md 文件作为纯文本返回（可选但推荐）
    location ~* .md$ {
        default_type text/markdown;
        add_header Content-Type text/markdown;
    }

    # 核心：SPA 路由回退机制
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 可选：缓存静态资源
    location ~* .(js|css|png|jpg|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

🔍 `try_files` 工作原理

bash 复制代码

try_files $uri $uri/ /index.html;

Nginx 按顺序尝试：

$uri → 是否存在同名文件？（如 /style.css、/guide/README.md）
$uri/ → 是否存在同名目录？（如 /guide/ 目录）
都不存在 → 返回 /index.html，交由 Docsify 前端处理路由

✅ 只要 .md 文件物理存在，就不会触发 fallback！

四、常见错误排查清单

问题	检查点	解决方案
`.md` 文件 404	文件是否真实存在于 `root` 目录下？	确认目录结构，如 `/var/www/docs/guide/README.md`
`.md` 被禁止访问	是否有 `location ~ .(md	txt)$ { deny all; }`？
请求路径错误	Docsify 的 `basePath` 是否配置错误？	若部署在根路径，设为 `basePath: '/'` 或省略
Nginx `root` 错误	`root` 是否指向了包含 `index.html` 的父目录？	确保 `root /path/to/site;` 下有 `index.html`

五、调试技巧

查看 Network 请求
- 打开 DevTools → Network → 刷新页面
- 查看 README.md、_sidebar.md 的请求 URL 和状态码
手动测试 .md 文件
- 在浏览器中直接访问：https://your-site.com/guide/README.md
- 应能下载或显示 Markdown 内容

检查 Docsify 初始化代码

xml 复制代码

<script>
  window.$docsify = {
    // basePath: '/docs/',  // ❌ 除非你部署在子路径
    loadSidebar: true,
    name: 'My Docs'
  }
</script>

六、最佳实践建议

不要用 alias 代替 root：容易导致路径混乱。
避免在 Nginx 中重写 .md 请求：让 Docsify 自己管理 Markdown 加载。
启用 Gzip 压缩：提升加载速度（Nginx 默认支持）。
添加 nojekyll 文件：如果你也考虑 GitHub Pages，可保留兼容性。

七、结语

Docsify 的魅力在于"零构建、实时渲染"，但这也对服务器配置提出了 SPA 式的要求。只要理解 "前端路由 vs 静态资源" 的区别，并正确配置 try_files，就能轻松部署一个高性能、可维护的文档站点。

🌐 你的文档值得被优雅地呈现 ------ 从正确的 Nginx 配置开始。

延伸阅读：