摘要：使用 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 文件。

---

二、典型问题现象

0. 首页正常，点击导航后空白或 404

   • 浏览器地址栏变为 /guide/，但页面无内容。

1. 控制台报错：Failed to load resource: the server responded with a status of 404

   • 通常是 README.md、_sidebar.md 等文件加载失败。

2. 手动访问 .md 文件返回 404 或被拒绝

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

---

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

✅ 基础配置模板

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 工作原理

try_files $uri $uri/ /index.html;

Nginx 按顺序尝试：

0. $uri → 是否存在同名文件？（如 /style.css、/guide/README.md）
1. $uri/ → 是否存在同名目录？（如 /guide/ 目录）
2. 都不存在 → 返回 /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

---

五、调试技巧

0. 查看 Network 请求

   • 打开 DevTools → Network → 刷新页面
   • 查看 README.md、_sidebar.md 的请求 URL 和状态码

1. 手动测试 .md 文件

   • 在浏览器中直接访问：https://your-site.com/guide/README.md
   • 应能下载或显示 Markdown 内容

2. 检查 Docsify 初始化代码

   <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 配置开始。

---

延伸阅读：

• Docsify 官方文档
• Nginx SPA 部署最佳实践