问答社区

原创作者: 图龙网络科技发布时间： 2023-09-23 258.35K 人阅读

网址导航程序支持一键部署至 Vercel，数据存储在 Github，零成本搭建一个网站导航！

太极混元发布于 1星期前分类：模板修改

🌟 核心特性

NavSphere 是一个基于 Next.js 14 构建的现代化导航管理平台，专为个人和团队打造的书签管理和导航门户解决方案。通过 GitHub 作为数据存储后端，提供安全、可靠的导航数据管理体验。

环境要求

Node.js 18.0+
pnpm 8.0+ (推荐) 或 npm/yarn
GitHub 账户

安装步骤

克隆项目

git clone https://github.com/tianyaxiang/NavSphere.git
cd NavSphere

安装依赖

pnpm install

配置环境变量

cp .env.example .env.local

启动开发服务器

pnpm dev

访问应用

打开浏览器访问 http://localhost:3000

✅ 现代技术栈

Next.js 14 (React 全栈框架)
TypeScript 5.1 (强类型保障)
Tailwind CSS 4 (原子化样式)
Radix UI (无障碍组件库)

✅ 安全认证

GitHub OAuth 登录 (NextAuth.js)
私有仓库数据加密存储

✅ 开发效率

拖拽排序界面 (React Flow)
智能搜索 (Fuse.js)
多语言支持 (i18next)

✅ 部署优化

Cloudflare Pages 全球加速
Docker 容器化部署
Vercel 一键部署

🛠️ 技术架构

技术栈	版本	用途
Next.js	14.2.3	服务端渲染 + API 路由
React	18.2.0	组件化开发
TypeScript	5.1.6	类型安全
Tailwind CSS	4.1.12	响应式样式
GitHub API	v4	数据存储与权限管理
React Query	5.62.2	数据获取与缓存
Zod	3.22.4	输入验证

⚙️ 快速开始

一键部署

https://vercel.com/button

部署后配置：

在 GitHub 创建 OAuth App (设置 GITHUB_ID/GITHUB_SECRET)
创建数据仓库 (默认 navsphere-data)
配置环境变量 (.env.local)

📝 配置指南

环境变量

env

复制

# GitHub OAuth 配置
GITHUB_ID=your-client-id
GITHUB_SECRET=your-client-secret

# 数据仓库配置
GITHUB_OWNER=your-username
GITHUB_REPO=data-repo-name
GITHUB_BRANCH=main

# 服务端配置
NEXTAUTH_URL=https://your-domain.com/api/auth
NEXT_PUBLIC_API_URL=https://your-domain.com

🚀 部署方案

Vercel 部署

点击部署按钮 → 自动拉取代码
配置环境变量 → 完成部署
更新 GitHub OAuth 回调地址：
https://your-vercel-app.vercel.app/api/auth/callback/github

Docker 部署

bash

复制

# 构建镜像
docker build -t navsphere:latest .

# 启动容器
docker run -d \
  -p 3000:3000 \
  -e GITHUB_ID=xxx \
  -e GITHUB_SECRET=xxx \
  --name navsphere \
  navsphere:latest

📊 数据结构

核心数据文件

文件名	用途	示例路径
`navigation.json`	导航菜单配置	`/data/nav.json`
`site.json`	站点全局配置	`/data/site.json`
`resources.json`	静态资源元数据	`/data/res.json`

数据格式示例

json

复制

// navigation.json
[
  {
    "id": "1",
    "title": "Dashboard",
    "icon": "dashboard",
    "link": "/dashboard"
  },
  {
    "id": "2",
    "title": "Settings",
    "icon": "settings",
    "children": [
      { "title": "Profile", "link": "/profile" },
      { "title": "Security", "link": "/security" }
    ]
  }
]

🔍 开发工具链

bash

复制

# 开发模式
pnpm dev

# 生产构建
pnpm build

# 代码检查
pnpm lint

# 启动服务
pnpm start

📦 项目结构

NavSphere/
├── app/          # Next.js 页面路由
├── components/   # 共享 UI 组件
├── data/         # 动态数据存储
├── features/     # 业务功能模块
├── styles/       # 全局样式
└── utils/        # 工具函数

注：完整文档已托管至 GitHub Wiki，包含：
✅ API 文档
✅ 贡献指南
✅ 版本更新日志
✅ 常见问题解答