网站导航 Wiki

website ，网站导航 & 项目推荐 & 工具推荐。

项目边界

website 是前台导航站，不是 CMS、后台系统或多用户收藏系统。

包含：

分类导航
站点搜索
卡片展示
3D 轨道展示
亮色 / 暗色主题
本地品牌素材
本地图标与离线 Iconify 图标
静态构建与部署

不包含：

登录系统
在线后台
数据库
云端收藏同步
用户权限管理
站点自动抓取审核流程

技术栈

模块	技术
页面框架	Nuxt 3
语言	Vue 3、TypeScript
3D 展示	Three.js
样式	自定义 CSS
数据来源	静态 TypeScript 数据
图标库	本地图片、Iconify JSON、sprite/iconfont
部署产物	Nuxt `.output`

核心依赖：

json

{
  "nuxt": "^3.12.4",
  "three": "^0.184.0"
}

常用脚本：

命令	作用
`pnpm run dev`	本地开发
`pnpm run build`	生产构建
`pnpm run generate`	静态生成
`pnpm run preview`	预览构建结果
`pnpm run typecheck`	类型检查
`pnpm run icons:export`	导出离线 Iconify 图标

目录结构

txt

website/
  app/
    app.vue
    assets/
      css/main.css
    components/
      navigation/
    composables/
      useThemeMode.ts
    data/
      navigation.ts
    pages/
      index.vue
    types/
      navigation.ts
    utils/
      iconify.ts
      iconify-static.ts
  public/
    brand/
    icons/
    logos/
    favicon.ico
  scripts/
    export-iconify-icons.mjs
  nuxt.config.ts
  package.json
  pnpm-lock.yaml

关键文件说明：

文件	作用
`app/pages/index.vue`	首页入口，负责搜索、分类、展示模式切换和页面布局
`app/data/navigation.ts`	分类、站点、合集、统计数据
`app/types/navigation.ts`	导航数据类型
`app/components/navigation/SiteCard.vue`	卡片模式站点项
`app/components/navigation/SiteLogo.vue`	站点 Logo 渲染
`app/components/navigation/NavigationRadarMap.vue`	3D 轨道模式
`app/components/navigation/CategoryRail.vue`	左侧分类导航
`app/components/navigation/LocalSpriteIcon.vue`	本地分类图标
`app/components/navigation/IconifyLogo.vue`	离线 Iconify 图标
`app/components/navigation/IconFontSymbol.vue`	iconfont symbol 图标
`app/components/navigation/NavigationWordmark.vue`	导航品牌字标
`public/brand/`	品牌素材
`public/logos/`	站点 Logo
`public/icons/site-sprite.svg`	分类等本地 symbol 图标
`public/icons/iconify/`	导出的离线 Iconify SVG
`scripts/export-iconify-icons.mjs`	从 Iconify JSON 导出本地图标

页面结构

首页只有一个公开路由：

txt

页面区域：

区域	说明
顶部栏	品牌 Logo、搜索框、主题切换
搜索摘要	分类数量、结果数量、展示模式切换
分类栏	当前可见分类列表，支持跳转
主内容区	卡片模式或轨道模式
页脚	Nuxt、Jerry-Up、邮箱、平台入口

展示模式

卡片模式

卡片模式用于高密度浏览，是默认展示方式。

能力：

按分类展示站点
左侧分类导航
搜索结果实时筛选
滚动时自动同步当前分类
站点卡片显示 Logo、标题、描述、标签
点击站点后新窗口打开目标地址

适用场景：

快速查找工具
批量浏览站点
核对分类内容
维护站点数据后做检查

轨道模式

轨道模式用于沉浸式浏览，把导航内容映射为一个 3D 空间。

视觉规则：

中心球体代表 Jerry-Up
分类展示为真实球体
网站作为分类球体周围的轨道节点
网站节点放大或悬停后展示 Logo 和详情卡片
不同分类尽量分布在不同水平线，减少重合

交互规则：

操作	效果
点击分类球体	聚焦该分类
长按分类球体	拖拽调整分类位置
点击网站节点	打开网站
悬停网站节点	暂停轨道运动并展示详情
点击中心球体	还原初始视角和布局
拖拽中心球体	旋转整体视角
`Esc`	退出聚焦

右上角控制：

图标	说明
`+`	放大视角，逐步显示更多网站
`-`	缩小视角，查看整体轨道
`↺`	重置视角和星球位置

右下角提示：

图标	说明
`Esc`	退出当前聚焦
`i`	悬停网站显示详情并暂停轨道
`↕`	长按分类球体拖拽调整位置
`◎`	拖拽中心球体旋转整体视角，点击可复位

搜索规则

搜索框支持匹配：

站点标题
站点描述
站点标签
分类名称

快捷键：

按键	作用
`/`	聚焦搜索框
`Esc`	清空搜索关键词

搜索行为：

空关键词显示全部站点
输入关键词后实时筛选站点
只显示包含匹配站点的分类
卡片模式下分类栏同步过滤后的分类

主题规则

项目支持亮色和暗色主题。

主题入口：

顶部栏主题切换按钮
useThemeMode.ts

主题影响：

页面背景
卡片颜色
分类导航状态
Logo 明暗版本
轨道模式辅助面板
页脚品牌素材

品牌图使用成对素材：

位置	暗色	亮色
顶部导航 Logo	`/brand/project-website-dark.svg`	`/brand/project-website-light.svg`
页脚 Jerry-Up Logo	`/brand/footer/logo-dark.svg`	`/brand/footer/logo-light.svg`
页脚平台 Logo	`/brand/footer/*-dark.svg`	`/brand/footer/*-light.svg`

数据模型

数据定义在：

txt

app/types/navigation.ts

分类

export interface NavCategory {
  id: string;
  label: string;
  description: string;
  icon: string;
  accent: string;
  order: number;
}

字段说明：

字段	说明
`id`	分类唯一标识
`label`	分类显示名称
`description`	分类说明
`icon`	分类图标名，对应 `site-sprite.svg`
`accent`	分类强调色
`order`	分类排序

站点

export interface NavSite {
  id: string;
  title: string;
  url: string;
  description: string;
  categoryId: string;
  tags: string[];
  icon?: string;
  image?: string;
  iconify?: string;
  featured: boolean;
  pinned: boolean;
}

字段说明：

字段	说明
`id`	站点唯一标识
`title`	站点名称
`url`	站点链接
`description`	简短说明
`categoryId`	所属分类
`tags`	搜索和展示标签
`image`	本地 Logo 路径
`iconify`	离线 Iconify 图标
`icon`	iconfont symbol 图标
`featured`	精选标记
`pinned`	高频标记

合集

export interface NavCollection {
  id: string;
  title: string;
  description: string;
  siteIds: string[];
}

字段说明：

字段	说明
`id`	合集唯一标识
`title`	合集名称
`description`	合集说明
`siteIds`	合集包含的站点 ID

分类字典

分类定义在：

txt

app/data/navigation.ts

当前分类：

ID	名称	用途
`tool`	在线工具	高频效率工具、检测工具与在线转换入口
`stats`	统计数据	市场趋势、开放数据与互联网统计入口
`network`	网络工具	网络检测、DNS、IP 与路由信息查询
`docs`	云文档	多人协作、沉淀知识与快速记录
`ai`	AI 应用	对话、创作、信息获取与工作流助手
`share`	快速分享	网盘、图床与跨端文件传输
`git`	开源社区	代码托管、协作与项目发布阵地
`server`	云厂商	服务器、云平台与基础设施入口
`official`	官方网站	开发基础设施与核心技术官网索引
`image`	找图	图标、壁纸、素材与视觉灵感来源
`audioBook`	书影音	文档、视频、音乐与影音资源入口
`work`	找工作	求职、校招与技术岗位寻找入口
`strolling`	逛逛	资讯、内容社区与休闲浏览入口
`navigation`	网站导航	优秀导航站与互联网整理项目

合集字典

当前合集：

ID	名称	用途
`data-watch`	数据观察	统计、趋势与网站数据入口
`ai-workbench`	AI 工作台	常用对话、灵感和效率工具
`developer-stack`	开发常用栈	官网、代码托管和网络检测工具
`creator-kit`	设计与内容素材	图标、壁纸、素材和云文档协作入口
`job-hunt`	求职面板	技术招聘与岗位入口

图标体系

站点 Logo 由 SiteLogo.vue 统一渲染，优先级如下：

image
iconify
icon
站点名称前两个字符兜底

本地 Logo

位置：

txt

public/logos/

写法：

createSite(
  'tool-bejson',
  'tool',
  'BEJSON',
  'https://www.bejson.com/',
  'JSON、编码、格式化',
  { image: '/logos/bejson.png' }
)

使用规范：

优先使用透明背景 SVG 或 PNG
图标应清晰可辨
文件名使用小写英文、数字和短横线
不使用无关默认图片伪装真实 Logo
缺失真实图标时可以暂时不配置 image

离线 Iconify

Iconify 数据来源：

@iconify-json/devicon
@iconify-json/logos
@iconify-json/simple-icons
@iconify-json/skill-icons

导出脚本：

txt

scripts/export-iconify-icons.mjs

导出命令：

bash

pnpm run icons:export

输出位置：

txt

public/icons/iconify/{collection}/{name}.svg
app/utils/iconify-static.ts

写法：

createSite(
  'official-vue',
  'official',
  'Vue.js',
  'https://vuejs.org/',
  '渐进式 JavaScript 框架',
  { iconify: 'logos:vue' }
)

维护要求：

新增 iconify 后执行 pnpm run icons:export
只使用脚本允许的集合
缺失图标数据时不要手写错误 ID
离线导出后页面不依赖 Iconify CDN

sprite/iconfont 图标

本地 sprite：

txt

public/icons/site-sprite.svg

iconfont symbol：

txt

public/icons/iconfont-symbol.js

使用场景：

分类图标
云厂商等暂未本地化的 symbol 图标
低优先级站点图标兜底

内容维护

数据维护入口：

txt

app/data/navigation.ts

新增站点

使用 createSite 新增站点：

createSite(
  'tool-example',
  'tool',
  '示例工具',
  'https://example.com/',
  '示例工具说明',
  {
    image: '/logos/example.png',
    tags: ['效率'],
    featured: false,
    pinned: false,
  }
)

新增要求：

id 全局唯一
categoryId 必须存在于分类字典
title 使用站点正式名称
url 使用可访问的正式入口
description 控制在一行内
tags 不超过 4 个
图标优先使用本地真实 Logo

修改分类

修改位置：

txt

navigationCategories

修改要求：

id 不随意变更
order 保持连续且可读
icon 必须能在本地 sprite 中找到
accent 使用现有色彩体系
删除分类前先迁移该分类下所有站点

修改合集

修改位置：

txt

navigationCollections

合集通过站点标题映射生成 siteIds。

维护要求：

合集数量保持克制
一个合集对应一个明确使用场景
合集标题短而具体
合集内站点优先选择高频入口

更新统计

统计数据：

export const navigationStats = {
  totalSites: navigationSites.length,
  totalCategories: navigationCategories.length,
  totalFeatured: navigationSites.filter((site) => site.featured).length,
  lastUpdatedLabel: '2026-06-04',
};

维护要求：

totalSites、totalCategories、totalFeatured 自动计算
批量更新站点后同步更新 lastUpdatedLabel
日期使用 YYYY-MM-DD

运行

进入项目：

bash

cd website

安装依赖：

bash

pnpm install

开发：

bash

pnpm run dev

默认访问：

txt

http://localhost:3000

构建：

bash

pnpm run build

静态生成：

bash

pnpm run generate

预览：

bash

pnpm run preview

部署

部署产物：

txt

.output

静态站点产物：

txt

.output/public

部署规则：

静态托管平台上传 .output/public
Node 服务部署使用 .output/server
.output 为构建产物，不作为源码维护
部署前执行构建或静态生成

推荐静态部署流程：

bash

pnpm install
pnpm run generate

然后发布：

txt

.output/public

质量检查

数据检查：

分类 ID 是否存在
站点 ID 是否唯一
URL 是否可访问
标题是否简短
描述是否准确
标签是否过多
Logo 路径是否存在
Iconify 图标是否已导出

页面检查：

卡片模式是否紧凑
轨道模式是否可进入
轨道模式分类是否错层
网站悬停是否显示详情
放大后 Logo 是否清晰
亮色 / 暗色主题是否正常
移动端是否无横向滚动
搜索结果是否准确

构建检查：

bash

pnpm run build

Iconify 检查：

bash

pnpm run icons:export

常见问题

页面没有显示 Logo

检查顺序：

image 路径是否存在
图片是否放在 public/logos/
路径是否以 /logos/ 开头
iconify 是否已执行导出
icon 是否存在于 iconfont symbol

Iconify 图标不显示

处理方式：

bash

pnpm run icons:export

然后检查：

public/icons/iconify/ 是否生成 SVG
app/utils/iconify-static.ts 是否包含对应 ID
iconify 字段是否使用 collection:name 格式

分类图标不显示

检查：

分类 icon 字段
public/icons/site-sprite.svg
LocalSpriteIcon.vue

轨道模式标签位置异常

检查：

NavigationRadarMap.vue
分类初始坐标函数
画布尺寸
标签投影逻辑
浏览器是否支持 WebGL

构建出现大 chunk 警告

该警告通常来自 Nuxt、Three.js 或页面主包体积。

处理建议：

不影响部署时可以保留
需要优化时再拆分 3D 组件或调整 Rollup chunk

`.output` 是否需要提交

.output 是构建产物，不作为源码提交。

源码维护重点：

app/
public/
scripts/
nuxt.config.ts
package.json
pnpm-lock.yaml

维护约定

提交前检查：

内容是否属于现有分类
新增 Logo 是否真实可识别
未使用图标是否已清理
pnpm run icons:export 是否需要执行
pnpm run build 是否通过
.output 是否未纳入版本控制

命名约定：

类型	规则
分类 ID	小写英文
站点 ID	分类前缀 + 站点英文名
Logo 文件	小写英文、数字、短横线
Iconify ID	`collection:name`
日期	`YYYY-MM-DD`

视觉约定：

卡片模式保持紧凑
轨道模式保持沉浸但可读
控制区优先使用图标
说明文案通过悬停提示展示
Logo 与文字间距保持统一
不使用外部网络图标作为强依赖

项目定位

website 是一个静态优先、长期维护、可持续扩展的个人导航站。

它承担三个角色：

Jerry-Up 的网站导航首页
日常高频工具的快速入口
个人品牌体系中的独立项目页

项目维护目标：

内容准确
图标稳定
页面清晰
交互顺手
构建可靠

网站导航 Wiki ​

项目边界 ​

技术栈 ​

目录结构 ​

页面结构 ​

展示模式 ​

卡片模式 ​

轨道模式 ​

搜索规则 ​

主题规则 ​

数据模型 ​

分类 ​

站点 ​

合集 ​

分类字典 ​

合集字典 ​

图标体系 ​

本地 Logo ​

离线 Iconify ​

sprite/iconfont 图标 ​

内容维护 ​

新增站点 ​

修改分类 ​

修改合集 ​

更新统计 ​

运行 ​

部署 ​

质量检查 ​

常见问题 ​

页面没有显示 Logo ​

Iconify 图标不显示 ​

分类图标不显示 ​

轨道模式标签位置异常 ​

构建出现大 chunk 警告 ​

.output 是否需要提交 ​

维护约定 ​

项目定位 ​

网站导航 Wiki

项目边界

技术栈

目录结构

页面结构

展示模式

卡片模式

轨道模式

搜索规则

主题规则

数据模型

分类

站点

合集

分类字典

合集字典

图标体系

本地 Logo

离线 Iconify

sprite/iconfont 图标

内容维护

新增站点

修改分类

修改合集

更新统计

运行

部署

质量检查

常见问题

页面没有显示 Logo

Iconify 图标不显示

分类图标不显示

轨道模式标签位置异常

构建出现大 chunk 警告

`.output` 是否需要提交

维护约定

项目定位