这篇讲的是我自用的个人导航站 YM Nav：一个跑在 Cloudflare Pages + Pages Functions + Workers KV 上的网址导航，单文件前端、带真后台管理，收藏数据全部存在自己的 KV 里，全部运行在免费额度内、不用服务器。这篇把「为什么做、有什么功能、怎么一步步部署、Fork 部署和原站到底差在哪、出问题怎么查怎么修」一次讲清，新手照着点也能搭出一个属于自己的。

一、为什么做它

浏览器自带的收藏夹有几个老毛病：换个浏览器、换台设备就对不上；攒了几百个网址之后，翻找全靠考古；有些网址只想自己看，不想混在给别人演示的清单里；还有些站「本地能不能直连、要不要挂梯」这种关键信息，收藏夹根本没地方记，只能把备注拼进标题里，名字越改越长、越看越乱。

市面上的导航站模板也不少，但大多是「一个静态页面 + 一份写死在代码里的链接清单」：加一个站要改代码、重新部署；想藏几个私人链接，要么藏不住，要么只能靠前端遮一遮——懂行的人打开接口一看全在里面。

所以我给自己定了几个硬指标，再动手：

  • 数据归自己：收藏不进代码仓库，只存自己的云端存储里，换设备打开就是同一份。
  • 加站不用改代码：有正经后台，点一点就能加分类、加链接、调顺序。
  • 隐私要真隐藏：不想公开的分类和链接，未登录的人连数据都拿不到，而不是页面上看不见、接口里全都有。
  • 不花钱、不伺候服务器：跑在免费额度里，部署完不用管。

YM Nav 就是按这四条做出来的。

二、功能全清单

浏览体验

  • 竖排卡片 + 分类视图：卡片是「图标 / 名称 / 域名」三段竖排，一屏能看更多；首页按分类堆叠展示，左上角「分类」菜单点某个分类就只看该分类，点「全部」回到整页；每个分类的展示样式（竖排 / 横排 / 纯文字）可以在分类编辑里单独选，后台「工具」里还能一键全站统一。
  • 顶部大搜索：站内实时过滤，也可以切换百度 / Google / Bing / GitHub 等外部搜索引擎。
  • 时钟与天气：实时时钟、问候语；天气按浏览器定位 → IP 定位自动获取（定位结果缓存 24 小时），城市名用简体中文地名服务。
  • 常去自动区：内置点击计数，打开多的网站自动排进首页「常去」区，越用越顺手。
  • 深浅色与壁纸：跟随系统或手动切换深色模式；自定义壁纸支持图片链接和本地上传两种（上传的存你自己的存储，不怕图床防盗链），遮罩浓度可在设置里手动调；标题文字会按背景图明暗自动配色，后台也能手动指定。
  • 网站图标自动抓取：没设图标的网站不用管，服务端自动去对方站里取它自己的图标（就是视频站卡片上那个台标的做法），取回来按域名缓存好；实在取不到才显示首字头像，不再依赖任何第三方图标服务。
  • 网站名称显示：卡片名称不再无脑省略——自动模式下，能缩字放进一行的缩字显示，放不下的自动换成两行，尽量让人看清这是什么站；后台可手动选「自动 / 两行显示 / 单行省略」。
  • 网站描述（长按显示）：每个网站可填一句描述，平时完全不显示、不占地方；长按卡片才弹出小卡，显示站名、网址和描述。

数据模型（本项目最在意的两件事）

  • 分类即顺序：数据按分类存储，没有全局排序编号。在某个分类里新增网站，它自动排在该分类末尾——告别「加一个站要重排全部序号」。
  • 本地 / 挂梯徽标：「能不能直连、要不要挂梯」是链接的正式字段，以彩色小标签显示在卡片角上（本地直连是绿色、需代理是橙色），不再拼进网站名字里，名字干干净净。

后台与安全

  • 真服务端鉴权：管理员密码以加盐 SHA-256 哈希存放在 KV 里，登录用 HttpOnly 会话 Cookie（7 天有效）；所有写数据接口一律校验会话，不是前端摆设。
  • 唯一的后台入口：双击首页大标题（站名）打开登录框——页面上没有任何显眼的管理按钮，入口只有你自己知道（手机端是双击手势识别）。
  • 隐私可见性：整个分类或单个链接都可以设为「仅登录可见」，未登录访客的接口响应里根本不包含这些数据，是服务端剔除，不是前端隐藏。
  • 代码与数据分离：仓库里只有代码，部署出来是空站；收藏、密码、点击记录只存在你自己的 KV 里，谁 Fork 这份代码都带不走你的数据。

管理功能

  • 分类与链接的增删改、分类内排序（上移 / 下移）、跨分类移动。
  • 站点英文名自动翻译：改中文站名时英文名自动生成（手改过则不再覆盖，也可一键重新翻译）。
  • 数据导入导出：JSON 整体备份 / 恢复；CSV 导入导出；Edge / Chrome 书签 HTML 同步合并（新站自动加进来、重复的自动跳过、按文件夹归类、原有的一条不动），也可以导出书签。
  • 收藏小工具：书签小工具（bookmarklet），在任何网页一键把当前页收藏进本站；也支持 /?add=网址 快速收藏。
  • 一键测活：后台「工具」里点一下，全站收藏挨个验活——正常 / 疑似失效 / 无法判定分开列，失效的当场就能删。
  • 键盘快捷键：/ 聚焦搜索框，Esc 清空搜索。
  • KV 暂时读不到时，自动用浏览器本地缓存顶上，不白屏。
ym-nav 实际界面（示例数据渲染）：分类卡片、常去自动排
ym-nav 实际界面（示例数据渲染）：分类卡片、常去自动排
ym-nav 手机版（示例数据）
ym-nav 手机版（示例数据）

三、特点与优点

  • 零月租：Pages、Functions、KV 全用 Cloudflare 免费额度，个人导航这点数据量和访问量，离额度上限远得很。
  • 不用服务器、不用数据库：没有主机要续费、没有补丁要打、没有进程要守护，部署完就是放着。
  • 数据全在自己手里：整站数据就是你 KV 里的一份 JSON，随时能一键导出成文件带走；平台只是存放的地方，不是牢笼。
  • 隐私是真隐私：私有分类在未登录时连接口数据里都不存在，这一点是很多「导航模板」做不到的——它们最多把卡片在页面上藏起来。
  • 手机友好：手机上打开就是完整的浏览和后台体验，加站、改站、测活都能在手机上完成；后台入口用双击手势，不依赖电脑。
  • 单文件前端：整个前端就是一个 index.html，无框架、无构建步骤，想看懂、想魔改，门槛都很低。
  • 代码和数据彻底分离：升级代码永远碰不到数据（原理见第五、六节），这是敢放心用的前提。

四、一步一步部署（新手向导）

全程在浏览器里点点点，不用写代码、不用命令行。大约几分钟能完成。推荐用「Git 连接部署」，下面就按这条路走。

第 0 步：准备两个账号

一个 GitHub 账号（放代码）、一个 Cloudflare 账号（放站点），都免费注册。

第 1 步：Fork 仓库到自己名下

打开仓库页，点右上角 Fork → 选自己的账号 → Create fork。这样你名下就有了一份自己的代码副本，后面 Cloudflare 连的就是你这份。

ym-nav 仓库主页：文件列表与 README 开头
ym-nav 仓库主页：文件列表与 README 开头

第 2 步：在 Cloudflare 建 Pages 项目并连接 Git

  1. 打开 Cloudflare 控制台 → 左侧 Workers 和 Pages → 创建 → 选 Pages → 连接到 Git。
  2. 授权并选择你刚 Fork 的那个仓库。
  3. 构建设置里：构建命令留空，输出目录填 /（就一个斜杠）。
  4. 点 保存并部署，等它跑完。此时站点已经能打开了，但先别急——数据功能还没接上，必须做完第 3、4 步。

第 3 步：创建一个 KV 命名空间

  1. Cloudflare 控制台 → 存储和数据库 → KV → 创建命名空间。
  2. 名字随便起（比如就叫 nav-data），创建完成即可。记住它，下一歩要选。

第 4 步：把 KV 绑到 Pages 项目上（最关键，别跳）

  1. 回到 Workers 和 Pages → 点进你刚建的 Pages 项目 → 设置 → 绑定 → 添加 → 选 KV 命名空间。
  2. 变量名必须填 NAV_KV（代码里写死的就是这个名字，填错一个字母都不行），命名空间选第 3 步建的那个，保存。
  3. 保存后重新部署一次绑定才生效：在项目的「部署」页签里，对最新一条部署点 … → 重新部署，或回仓库随便提交一个小改动触发自动部署。

第 5 步（可选）：绑自己的域名

Pages 项目 → 自定义域 → 填你的域名按提示走。没有域名也完全不影响使用，用 Cloudflare 分配的 pages.dev 地址即可（见第五节第 ⑤ 条）。

第 6 步：设置管理员

  1. 打开你的站点首页，双击最上方的大标题（站名），会弹出登录框。
  2. 因为是第一次，页面会让你设置管理员账号和密码——自己想一个，页面只存它的加盐哈希，不存明文。设完会自动登录。
  3. 以后进后台都是这个动作：双击标题 → 输账号密码。

第 7 步：把你的收藏搬进来

  • 从零开始：登录后台，逐个加分类、加网站即可（新站自动排到所属分类末尾，不用管排序编号）。
  • 从浏览器搬家：把 Edge / Chrome 的收藏夹导出成书签 HTML 文件，后台「数据」里用书签同步导入——它会按文件夹自动归类、重复的自动跳过、原有的一条不动。
  • 以后日常收藏：在任何网页点一下书签小工具，或者用 /?add=网址，顺手就存进来了。

上线自查清单

  • [ ] 首页能打开，时钟、天气、搜索都在
  • [ ] 双击大标题能弹出登录框，能用刚设的账号密码登录
  • [ ] 在后台加一个测试网站，刷新首页能看到；换个浏览器打开也能看到（说明数据真存进 KV 了）
  • [ ] 把一个分类设为「仅登录可见」，退出登录后确认它在首页彻底消失
  • [ ] 后台「数据」里导出一次 JSON 备份，确认能下载——这是以后的保命文件，先存一份

⚠️ 一个实测教训：不要图省事用「直接上传 zip」的方式部署。某些情况下直传部署不会生成 Functions，表现是网页能打开、但登录和数据全都不工作。Git 连接部署没有这个问题，而且以后改代码推送就能自动更新，所以只推荐方式一。

五、和原站的区别：Fork 部署后是什么样

先说结论：Fork 部署出来的，是一个和原站代码一模一样、但数据全空、归你全权所有的新站。逐条讲清：

① 你 Fork 到的是「空站」，这正是应该的。
作者的全部收藏数据存在作者自己的 KV 里，不在代码里、不会随 Fork 走——代码与数据从一开始就是分离的。所以你部署完打开，是一个干干净净的空导航，从零添加你自己的站点。这不是缺功能，这正是隐私设计本身：换作你的站被别人 Fork，你的收藏同样一条都不会被带走。

② 管理员账号密码由你自己设，没有默认密码可蹭。
首次打开、双击标题时，页面让你设置自己的管理员账号和密码，只存加盐 SHA-256 哈希。仓库里不存在任何「初始密码」「后门账号」，作者也不知道你设的密码是什么。

③ 没有「自动更新数据」这回事，代码升级要走同步——先说清为什么。
本站没有定时任务、不靠 Actions 在后台跑什么：你的收藏只由你自己增删改，不存在谁替你「更新数据」。代码升级是另一回事，卡点在一条通用规则上：Cloudflare 只自动部署它连接着的那一个仓库。原仓库更新了代码，不会自己流进你的 Fork——你得先把上游更新同步进你的 Fork，同步一完成、你的仓库有了新提交，Cloudflare 立刻就自动部署新版了。所以「没有自动更新」的准确说法是：差一个「同步」动作，部署本身仍然是全自动的。同步有三种做法，仓库 README 的「升级版本」一节有现成图文：

  • 手动 Sync fork（最简单）：打开你 Fork 的仓库主页 → 点分支上方的 Sync fork → 有新提交就点 Update branch，等它同步完，再去 Cloudflare 控制台确认最新部署变绿勾，最后打开站点核对一下收藏数量、登录、私密分类是否正常。
  • 全自动同步（可选进阶）：在你自己的 Fork 里加一个 README 现成给好的工作流文件（.github/workflows/sync-upstream.yml，内容照抄即可），再去 Fork 的 Actions 页点一次启用。此后 GitHub 每天自动把上游合并进你的 Fork 并推送，Cloudflare 随即自动部署——彻底不用管。用不用加？上游更新并不频繁，新手完全可以先不加，想升级时手动点一次 Sync fork 就够；等你觉得手动同步烦了，再加也就十分钟的事。两个注意事项：Fork 的 Actions 默认是关闭的，必须先去启用；仓库 60 天没有任何活动，GitHub 可能自动暂停定时工作流，去 Actions 页重新启用即可。
  • 本地 git 推送：会用 git 的人，拉下来改完推上去，同样自动部署。

还有一句最要紧的：升级只换代码，不碰数据。收藏、设置、管理员密码、点击记录全在 KV 里，同步代码不会覆盖它们。升级前按第六节的规矩导一份 JSON 备份，就万无一失。

④ Fork 只复制代码，云端资源一概不带。
这是 GitHub 的通用规则：Fork 拿到的只有仓库里的代码文件，不复制原仓库的 Secrets，也不会在 Cloudflare 那边替你生成任何东西。所以 KV 命名空间要自己建、绑定要自己加（第四节第 3、4 步），Pages 项目也是连你自己的 Fork。这几步做完，这个站从代码到数据就全是你的了。

⑤ 域名各用各的。
原站绑的是作者自己的域名。你的站默认用 Cloudflare 免费分配的 pages.dev 地址就能正常用；有自己的域名，就在 Pages 项目的「自定义域」里绑上，互不影响。

六、出问题怎么办：检查与维修

先记住三个「在哪看」：

  • 部署状态：Cloudflare 控制台 → Workers 和 Pages → 你的项目 → 部署，看最新一条是成功还是失败，失败了点进去看部署日志。
  • 数据与绑定：同项目 → 设置 → 绑定，确认 NAV_KV 还在、指向的命名空间没变；命名空间本体在控制台 → 存储和数据库 → KV 里。
  • 现成答案：仓库 README 的「常见问题」一节和「升级版本」一节，先翻一遍，多数毛病都在里面写了。

常见故障对照表：

症状多半是什么怎么修
双击标题没反应、进不了后台弹窗被浏览器拦截，或手势没识别换个浏览器试；在首页标题上稳稳双击（手机端是双击手势，多试一次）
登录不上 / 管理员密码忘了密码记错，或哈希对不上到 Cloudflare 控制台 → 存储和数据库 → KV → 打开你的命名空间 → 删掉 admin 这个 key → 回站点双击标题，会重新进入首次设置流程，设个新密码即可。收藏数据不受任何影响
站点打不开（报错或空白）最新一次部署失败，或项目异常查「部署」列表：最新一条失败就看日志，或对上一个成功的部署点 … → 回滚到此部署，立即恢复
网页能打开，但数据空白、登录无效这次部署没带上 Functions（接口 /api/config 返回的不是 JSON）等一两分钟刷新重试，或在部署列表里重新部署一次；如果当初是「直接上传」部署的，改用 Git 连接部署（第四节的方式一）根治
数据不见了 / 收藏全没了KV 绑定丢了、变量名被改，或命名空间被误删先查「设置 → 绑定」里 NAV_KV 是否还在、指向对不对；绑定丢了就按第四节第 4 步重新绑上再重新部署。真把命名空间删了，就登录后台在「数据」里导入你之前导出的 JSON 备份整体恢复
升级后条数对不上、功能不对劲同步时代码冲突没处理干净，或新版改了数据结构先用部署回滚退回上一个成功版本；再看 README 更新日志里 version 字段有没有变化说明；最后用升级前导出的 JSON 备份在「数据」里导入恢复
天气不显示 / 图标刷不出来定位被拒，或对方站图标取不到天气会按浏览器定位 → IP 定位自动兜底，稍等再看；图标取不到会自动回退成首字头像，不影响使用

升级防丢数据的铁规矩（每次升级前必做）：

  1. 登录后台 →「数据」→ 导出 JSON，备份文件存好。这是唯一的保命手段：只要备份在，任何升级事故都能一键导回来。
  2. 记下首页显示的「共 X 个网站 · Y 个分类」，升级后核对条数。
  3. 不要删除或重建 KV 命名空间，不要改绑定变量名 NAV_KV——数据全在里面，删了等于清空站点。
  4. 升级后验证三件事：首页能打开且条数不变、双击站名能登录、私密分类在未登录时看不到。三项都过，才算升级完成。

七、隐私与边界

  • 私有区是服务端真隐藏：分类或链接设为「仅登录可见」后，未登录访客拿到的接口响应里根本不包含这些数据——不是把卡片在页面上藏起来那种假隐藏，扒接口也扒不到。
  • 收藏只活在你自己的 KV 里：整站数据就一份 JSON（外加管理员哈希、会话、点击计数几个 key），都在你 Cloudflare 账号的 KV 命名空间里，不经过任何第三方，不在代码仓库里。仓库公开也不怕——里面只有代码。
  • 后台入口不显眼：页面上没有管理按钮，入口只有双击标题这一条路，密码只存哈希，会话是 HttpOnly Cookie。
  • 没有在线演示是故意的：导航站的价值就是里面收藏的网址，那些是个人数据，不适合公开；想看效果，仓库里有效果预览图（示例数据渲染），或者花几分钟部署一个自己的。
  • 边界也要说清：它就是一个个人导航，不做多用户、不做公开投稿；运行在 Cloudflare 免费额度内，个人使用绰绰有余；万一 KV 暂时读不到，页面会先用浏览器本地缓存顶上不白屏，但增删改要等 KV 恢复才算数。

八、地址汇总

最后：这篇文章就发在我自己的博客上，而博客的上一篇，讲的正是这个博客本身怎么搭。这一套自建小工具——博客、导航、后面的几篇还会写到的其他几个站——共同的规矩都是这一句：代码可以公开，数据永远只在自己手里。