发现导航源码笔记：把 JSON 当数据库的纯静态导航站-星海夜航

发现导航（仓库 liuzi6612/nav）是一个纯静态导航站，3300+ star，TypeScript 写的。README 用一句话概括目标：无数据库、无服务器、零成本一键部署、开箱即用，但又能像数据库那样操纵数据和保存。功能面比一般静态导航宽得多：内置 800+ 网站、浏览器书签双向导入导出、AI 翻译、用户提交增删改、暗黑模式、PWA（可装到桌面、能离线打开的网页应用）、多款主题切换。

是什么

前端是 Angular（README 的技术徽章和仓库里的 angular.json 都对得上）加 ng-zorro-antd、Tailwind，PWA 由 @angular/service-worker 提供。数据不在数据库里，在仓库的 data 目录：db.json 存分类与站点（数组，一项一个分组，分组里挂 url 列表），search.json 存搜索引擎，tag.json、component.json、settings.json 分别管标签、小组件和站点设置。构建期由 scripts/build.ts 读这几个 JSON，生成 SEO（搜索引擎收录）用的 HTML 片段、写 PWA manifest，同时统计打不开的地址数量——README 那条「支持检测网站存活状态」走的就是这条路。图标不放主仓库，另走一个图片仓库/分支，配置项叫 imageRepoUrl。

没做到的部分：它不提供真正的服务端账号体系。所谓「支持后台管理，无需部署」是把路由地址改成 system 就进后台，改动最终落回 Git 仓库；只有自有部署才需要 README 配置表里的 password 和 mailConfig。

技术栈与部署

README 给两条路线：Fork + GitHub Pages 免费托管，以及自有部署（pm2 / Docker / 宝塔）。Fork 路线写得最细，基本照抄：

# 摘自 README 的 Fork 部署步骤
1、右上角 Fork 当前项目
2、在 github.com/settings/tokens/new 申请 token，勾选读写权限
3、打开自己仓库的 Actions，确认已开启自动部署
4、修改根目录 nav.config.yaml，改 gitRepoUrl 字段
5、访问 https://你的用户名.github.io/nav
   若 404，去 Settings/Pages 检查发布分支是否为 gh-pages

Netlify 只需把打包路径设为 dist/browser；Vercel 和 Cloudflare Pages 在 README 里只给了链接，没有额外参数。升级用 README 的 git fetch upstream main + git merge 那几条，装了 Node 的话直接 npm run update。本地开发的启动命令和 Node 版本要求 README 没写，得自己试（package.json 里也没声明 engines）。

值得抄的三点

数据组织：分组数组 + 每条站点可关联多个网址或多个标签，JSON 放在仓库里，配一个带读写权限的 token，站点就能「自己提交自己」。这套结构天然可 diff、可回滚、可 review，比数据库多了审计，比手写 HTML 多了结构化。抄的时候把图片仓库拆出去这步别省，主仓库不会被图标文件撑大。
搜索与分组交互：引擎是 search.json 里的可配置数据，不是硬编码几个 tab；配合 README 说的三叉树分类（分类 / 子分类 / 站点）和 hash 路由，纯静态托管也能保住可分享的深链接。README 明确提醒：部署在 GitHub Pages 时 hashMode 务必设为 true。
重活放到构建期：SEO 片段、PWA manifest、存活检测都在 build 时算完，运行时就是静态文件。这是它「零成本托管」和「有后台体验」能同时成立的原因，也是同类项目最该抄的架构决定。

别踩的坑

Fork 模式不要填 address 和 password。nav.config.yaml 的注释写得很清楚：一旦填了 address 就按自有部署处理，行为分支和 Fork 完全不同。
main 分支上的 data/db.json 是 0 字节空文件（我抓下来确认过）。第一次跑起来看不到内置站点是正常现象，数据由部署流程生成；README 没解释这点，得自己试。
后台入口靠 /system 这个路径名「隐藏」，Fork 出去的站是公开仓库 + 公开页面，任何人都能猜到入口地址。README 提到「支持配置仅自己可见」，但隔离强度没写，别把内部系统链接放上去。
升级命令带 --allow-unrelated-histories，说明历史是拼接的，真起冲突时 README 没给处理办法。

许可证

GPL-3.0，Copyright 2024-present。README 同时挂了商业授权的说法：兼容开源的项目和非商业用途走 GPL，想让源码保持私有就得购买授权。版权人对自己的代码做双重许可是合法的，但作为使用者要记住 GPL 的传染性：分发基于它的衍生作品时，整体源码同样要以 GPL 公开。nav.config.yaml 头部还写着「未授权可免费使用，必须公开可见，禁止商业用途」，比 GPL 更严，两处口径不一致时按最保守的理解走。

文章版权归作者所有，未经允许请勿转载。

THE END