88531.cn 全站导航页开发文档

这个项目是什么

site-nav 是 88531.cn 自有站点矩阵的静态导航页（在线地址 https://nav.88531.cn/），把 21 个站点、6 大分类收在一个页面里，一键直达。它解决的问题很具体：自己手上散落着一堆子域名站点（图床、影视聚合、工具箱、代码托管、博客……），没有一个统一入口。整个项目是纯静态单文件，没有构建步骤、没有依赖、没有任何第三方统计与追踪，改完刷新浏览器就能看到效果，非常适合当「个人站点矩阵的门面」来二次开发。

技术栈与架构

语言：原生 HTML + CSS + JavaScript，全部写在 index.html 一个文件里。
无框架、无打包器、无 npm 依赖，不需要 npm install，也不需要 Node 作为运行时（node --check 只在开发自检时用到）。
数据驱动渲染：页面底部 <script> 里的 SITES 数组是唯一数据源，页面卡片由它生成，不是手写死的 HTML。
交互全部靠浏览器原生 API：IntersectionObserver 做滚动高亮，prefers-color-scheme 做明暗自适应，writing-mode: vertical-rl 做手机端竖排分类文字。

仓库结构

site-nav/
├── index.html      # 全部页面（HTML + CSS + JS 单文件）
├── CHANGELOG.md    # 更新日志（v1.0.0 ~ v1.6.0，按日期倒序）
├── README.md       # 项目说明与维护方法
└── LICENSE 说明在 README 内（MIT © 2026 88531.cn · 软师兄）

顶层只有三个文件，结构极简：index.html 是全部实现，CHANGELOG.md 记录版本，README.md 记录维护约定。

页面实现要点

以下都是 index.html 内部的真实实现，改版时需要一起照顾到：

深色固定竖栏导航：桌面端侧栏宽 212px 横排分类列表；屏幕宽度 ≤900px 时自动收窄为 54px 窄条，分类文字用 writing-mode: vertical-rl 竖排，把内容区让出来。
滚动自动高亮：用 IntersectionObserver 监听各分类区块，滚动到哪个分类，侧栏对应项渐变高亮；点击侧栏平滑跳转，跳转后 900ms 内抑制回调覆盖，避免高亮被瞬时顶掉。
实时搜索：按名称 / 域名 / 描述过滤站点卡片，同时隐藏没有结果的分类侧栏项。
favicon 自取：直接加载各站自己的 /favicon.ico，加载失败自动回退到内置 emoji（SITES 里的 icon 字段），不依赖第三方图标聚合服务。
明暗自适应：跟随系统 prefers-color-scheme。
移动端适配：≤560px 收成单列卡片、间距收紧，README 记录实测无横向溢出。

站点数据维护（唯一的数据入口）

站点清单在 index.html 底部 <script> 中的 SITES 数组，每项格式：

{cat:"分类名", icon:"🐙", name:"站点名", host:"example.com", path:"/可选路径", live:true,
 desc:"一句话描述"},

cat 决定归属分类与侧栏分组，host + path 拼出链接与「复制」按钮内容，live 参与在线数统计，desc 是一句话描述。README 特别强调：每个站点的名称与描述都来自实测 HTTP 响应标题，不是杜撰的，新增站点时也应照此填写。

新增或删除站点后必须同步更新统计数字——stTotal / stLive / vis / total 这几个初始值写在页面里，改了站点不改数字会出现「21 站」和实际卡片数对不上的情况。

本地开发环境

没有安装步骤，打开即改：

git clone http://127.0.0.1:3200/jinghui/site-nav.git
cd site-nav
# 修改 index.html，按 README 要求跑一次 node --check 确认 JS 语法

node --check 是 README 明确要求的自检动作：SITES 数组里对象末尾漏一个逗号，会让整段 JS 报语法错、整页渲染为空。改完直接用浏览器打开 index.html 预览即可，无需起服务。

构建与发布

本项目没有构建环节，发布就是覆盖单文件。页面发布在宝塔站点 /www/wwwroot/nav.88531.cn/：

scp index.html root@<vps>:/www/wwwroot/nav.88531.cn/index.html

二次开发要点

漏逗号是头号坑：SITES 每项末尾的逗号不能省，CHANGELOG v1.5.0 记录过因此导致页面整体渲染为空的事故，改完务必 node --check。
统计数字与站点数要联动：v1.6.0 新增 Gitea 站点时同步把口径改成「22 站 / 6 分类」，只加卡片不改数字会被用户一眼看出来。
长域名卡片布局：v1.5.0 修过长域名把「复制」按钮挤到竖排换行的问题，卡片用 flex 布局让 URL 自动省略、按钮不换行，改卡片结构时注意保留。
接口类站点要标注：二维码这类接口域名直访可能 403 属正常，v1.1.0 起卡片上带「接口」徽标提示，别当成坏链删掉。
高亮定位阈值：高亮带取视口正中会错位，实际实现改为贴顶 6%~20% 区间，并加了首分区归位处理，调整滚动逻辑时这两处别回退。

更新记录（摘自 CHANGELOG.md）

v1.6.0：新增「自建 Gitea 代码托管」gitea.88531.cn，共 22 站 / 6 分类；新增 CHANGELOG 与 README，首次推送自建 Gitea。
v1.5.0：手机端导航改为窄条竖排文字（54px）；新增 tv.88531.cn、it.88531.cn，共 21 站 / 6 分类。
v1.4.0：分类导航改为左侧固定竖栏，滚动自动高亮（IntersectionObserver）。

88531.cn 全站导航页 开发文档