为什么 Docbase 访问文件夹不报 404？SPA hash 路由与 fallback 设计深度解析
【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase
Docbase 是一款将.md文件一键变成版式精美文档站的开源工具（Turn .md files into beautiful sites），自带版本管理与离线搜索。很多新手都会疑惑：为什么在 Docbase 生成的文档站里，直接访问某个"文件夹"的 URL，却不会出现 404 页面？答案藏在两个经典设计里——SPA hash 路由与多层 fallback。本文带你用 5 分钟彻底搞懂。🔍
先认识 Docbase：它到底部署了什么？
与传统"一个 Markdown 对应一个 HTML"的静态文档站不同，Docbase 是一个单页应用（SPA）：
- 整个站点只有一个页面外壳 index.html，里面只有一块
ng-view容器； - 所有逻辑打包在
dist/目录的 JS 里； - 正文内容（
docs/下的.md文件）由浏览器运行时按需抓取再渲染。
也就是说，服务器上根本没有"每个文件夹一个 HTML"这回事。这正是后面一切不报 404 的根源。
第一重保险：hash 路由，服务器"看不见"你的路径
📌 核心机制：URL 中#后面的部分永远不会发给服务器。
对比一下两种 URL：
| 模式 | URL 示例 | 服务器收到的请求 |
|---|---|---|
| hash 路由（默认） | yoursite.com/#/v1.0/folder2/file1 | 只请求index.html |
| 干净路径（HTML5 模式） | yoursite.com/v1.0/folder2/file1 | 请求v1.0/folder2/file1文件 |
在默认的 hash 模式下，无论你"访问文件夹"还是"访问文件"，浏览器都只加载同一个index.html，剩下的#/v1.0/folder2交给前端 JavaScript 解析。服务器压根没参与路由，404 从何而来？💡
这一行为由 scripts/docbase.js 中的路由配置决定，其中$location.html5Mode(Docbase.options.html5mode)是关键开关；而默认值html5mode: false写死在 docbase-config.js 与 docbase.json 中。
第二重保险：为"文件夹"单独注册路由
就算路径真的到了前端，Docbase 也在路由表里显式为文件夹准备了一条规则，这就是 v0.2.56 版本日志里那句 "No 404s when navigating to folders" 的实现：
| 路由规则 | 匹配到 | 渲染结果 |
|---|---|---|
/:version/:folder/:file | 具体文档 | 文档内容页 |
/:version/:folder | 文件夹 | 该文件夹的index 目录页 |
/:version | 版本 | 版本首页 |
/ | 根路径 | 站点主页 |
otherwise | 其他一切 | 重定向回/ |
两个巧妙的小设计：
- 自动注入 index：
Docbase._index（见 scripts/docbase.js）会为每个文件夹自动补一个index文件，所以"文件夹"天然有默认落地页； - 优雅降级：
Route.updatePath（见 scripts/docbase.js）在发现版本、文件夹或文件不在映射表里时，不会让页面崩溃，而是标记fail并把路径平滑回退到最近的合法层级（比如回退到/{version}或/）。
侧边栏里每一条导航链接也都是#/版本/文件夹/文件形式（参考 html/flatdoc.html），整套体系自洽闭环。✅
进阶：html5mode 开启后，404 会回来吗？
会的。如果你把 docbase-config.js 中的html5mode改为true，URL 会变成干净的/v1.0/folder2——但此时服务器真的会收到这个路径请求，若服务器没有配置"找不到文件就返回 index.html"的 fallback 规则，刷新页面就会 404。
源码注释也明确提醒：HTML5 模式只适合自托管且可配置服务器的场景（见 scripts/docbase.js）。所以：
- 托管在 GitHub Pages 等静态平台 → 用默认 hash 模式，零配置永不 404；
- 自己掌控 Nginx/Apache → 可开 HTML5 模式换取更美的 URL。
三步体验：动手复现"永不 404"的文档站 🚀
- 克隆仓库：
git clone https://gitcode.com/gh_mirrors/do/Docbase - 改配置：编辑 docbase-config.js，把
versions里的版本、文件夹、文件对应到你docs/目录下的真实结构（可参考docs/v1.0/、docs/v2.0/的示例文件）； - 本地起静态服务：在根目录用任意静态服务器（如
python -m http.server）打开站点，然后故意在地址栏输入#/v2.0/folder2试试——你会看到一个整齐的文件夹目录页，而不是 404。
常见问题快问快答
Q：访问一个不存在的文件会怎样？A：hash 模式下otherwise规则会把你重定向回主页/；updatePath也会先做映射校验，页面不会白屏。
Q：hash 路由有什么缺点？A：URL 带#不够美观，书签分享略长。这是用"URL 颜值"换"零服务器配置"的经典权衡。
Q：能自定义 URL 结构吗？A：可以。三级结构版本/文件夹/文件在 scripts/docbase.js 的路由表中定义，配合versions配置即可调整文档层级。
写在最后
Docbase "访问文件夹不报 404" 并不是某个黑科技，而是三层设计的合力：hash 路由让服务器不参与寻址 → 为文件夹单独注册路由让目录有默认落地页 → otherwise 与 updatePath 兜底让任何非法路径都能优雅回退。这套"路由 + fallback"的组合拳，是学习 SPA 前端路由设计时非常值得精读的开源范例。📖
【免费下载链接】DocbaseTurn .md docs into beautiful sites项目地址: https://gitcode.com/gh_mirrors/do/Docbase
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
