VidNav | 现代化的内容导航管理平台 | 视频导航 + 网址导航 - 话题详情

项目地址

https://github.com/tianyaxiang/vidnav

📖 项目简介

VidNav 是一个基于 Next.js 15 构建的现代化导航管理平台，集成了视频导航和网址导航两大核心功能。专为内容收藏、分类和管理而设计，通过 GitHub 作为数据存储后端，提供安全、可靠的导航数据管理体验。

双核心功能

🎬 视频导航

专注于视频内容的收藏和组织，支持 Bilibili 和 YouTube 平台的视频管理。

🔖 网址导航

全面的网站书签管理系统，帮助你收藏和整理常用网站、在线工具和资源。

核心亮点

🎬 多平台视频支持：完美支持 Bilibili 和 YouTube 视频播放
🔖 网址导航管理：收藏和管理你的常用网站和在线工具
📊 分类管理：灵活的分类和子分类系统，支持无限层级
🎨 现代化界面：基于 Radix UI 和 Tailwind CSS 的精美界面
🔐 GitHub 认证：基于 NextAuth.js 的安全登录
📱 响应式设计：完美适配桌面端和移动端
🌓 主题切换：支持深色/浅色主题
🎯 智能图标：自动获取网站 Favicon
⚡ 高性能：支持 Cloudflare Pages 边缘部署

✨ 核心特性

视频管理功能

🎥 视频分类：支持多级分类和子分类，灵活组织视频内容
🎯 视频配置：自动识别 Bilibili 和 YouTube 视频链接，提取视频信息
🖼️ 封面管理：支持自定义上传视频封面图片
🎬 内嵌播放：支持在站内直接播放 Bilibili 和 YouTube 视频
📝 详细信息：为每个视频添加标题、描述等详细信息
🔄 拖拽排序：通过拖拽轻松调整视频和分类的顺序

网址导航功能

🔖 网站收藏：快速收藏和管理你喜欢的网站
📂 分类组织：创建主分类和子分类，无限层级的目录结构
🎨 智能图标：自动获取网站 Favicon，也可手动上传
📝 详细描述：为每个网站添加标题、描述等信息
🔍 快速搜索：通过关键词快速定位网站
🎯 一键访问：点击即可跳转到目标网站
🏷️ 标签管理：使用图标和标签更好地组织内容
🔄 拖拽排序：自由调整网站和分类的显示顺序

管理后台功能

👨‍💼 统一管理：视频和网址统一的后台管理系统
➕ 快速添加：
- 视频：粘贴视频链接即可添加 Bilibili 或 YouTube 视频
- 网址：输入 URL 自动获取网站信息
✏️ 编辑功能：
- 修改标题、描述、图标
- 调整分类归属
- 上传自定义封面/图标
🗂️ 分类管理：创建、编辑、删除分类和子分类
📊 可视化编辑：Monaco Editor 支持 JSON 数据直接编辑
🔍 智能搜索：快速定位内容和分类
🎨 图标选择：集成 Lucide Icons 图标库

技术特性

🚀 现代技术栈：Next.js 15 + React 18 + TypeScript
🎨 UI 组件库：Radix UI + shadcn/ui
🎭 图标系统：Lucide React 图标库
📦 状态管理：React Query 数据获取和缓存
🔧 表单处理：React Hook Form + Zod 验证
🌐 数据存储：GitHub 仓库作为数据后端
🔐 身份认证：NextAuth.js v5 OAuth 认证

🛠️ 技术架构

技术栈	版本	用途
Next.js	15.5.7	React 全栈框架
React	18.2.0	用户界面库
TypeScript	5.1.6	类型安全的 JavaScript
Tailwind CSS	4.1.12	原子化 CSS 框架
NextAuth.js	5.0.0-beta.25	身份认证解决方案
Radix UI	Latest	无障碍 UI 组件库
Lucide React	0.462.0	现代图标库
React Query	5.62.2	数据获取和状态管理
React Hook Form	7.53.2	表单处理
Zod	3.25.76	数据验证
Monaco Editor	0.52.2	代码编辑器

🚀 快速开始

环境要求

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

安装步骤

克隆项目

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

安装依赖

pnpm install

配置环境变量

cp .env.example .env.local

编辑 .env.local 文件，配置必要的环境变量（详见下方配置指南）

启动开发服务器

pnpm dev

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

⚙️ 配置指南

环境变量设置

创建 .env.local 文件并配置以下变量：

# GitHub OAuth App 配置
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# GitHub 仓库配置
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-repo-name
GITHUB_BRANCH=main

# GitHub Fine-grained PAT (用于匿名投稿创建 Issue)
GITHUB_PAT=your-github-personal-access-token

# NextAuth 配置
NEXTAUTH_URL=http://localhost:3000/api/auth
NEXT_PUBLIC_API_URL=http://localhost:3000

GitHub OAuth App 设置

创建 OAuth App
- 访问 GitHub Developer Settings
- 点击 "New OAuth App"
- 填写应用信息：
  Application name: VidNav Homepage URL: http://localhost:3000 Authorization callback URL: http://localhost:3000/api/auth/callback/github
获取凭据
- Client ID: 应用详情页显示
- Client Secret: 点击 "Generate a new client secret" 生成

GitHub 数据仓库设置

创建数据仓库
- 访问 GitHub New Repository
- 仓库名建议: vidnav-data
- 可选择 Public 或 Private
初始化数据文件 项目会自动创建以下数据文件：
- videos.json - 视频数据
- navigation.json - 导航数据
- site.json - 站点配置

📊 数据结构

videos.json - 视频数据格式

视频导航的数据存储格式：

{
  "navigationItems": [
    {
      "id": "category-id",
      "title": "分类名称",
      "icon": "Home",
      "description": "分类描述",
      "enabled": true,
      "items": [
        {
          "id": "video-id",
          "title": "视频标题",
          "href": "视频链接",
          "description": "视频描述",
          "icon": "/assets/cover/cover.jpg",
          "enabled": true,
          "videoConfig": {
            "type": "bilibili",
            "bvid": "BV1xxxxxxxxx",
            "aid": "xxx",
            "cid": "xxx",
            "p": 1
          }
        }
      ],
      "subCategories": [
        {
          "id": "sub-category-id",
          "title": "子分类名称",
          "icon": "PlayCircle",
          "enabled": true,
          "items": []
        }
      ]
    }
  ]
}

navigation.json - 网址导航数据格式

网址导航的数据存储格式：

{
  "navigationItems": [
    {
      "id": "category-id",
      "title": "常用推荐",
      "icon": "Star",
      "description": "常用网站和工具",
      "enabled": true,
      "items": [
        {
          "id": "item-id",
          "title": "网站名称",
          "href": "https://example.com",
          "description": "网站描述",
          "icon": "/assets/images/logos/example.webp",
          "enabled": true
        }
      ],
      "subCategories": [
        {
          "id": "sub-category-id",
          "title": "子分类名称",
          "icon": "BookOpen",
          "description": "子分类描述",
          "enabled": true,
          "items": [
            {
              "id": "sub-item-id",
              "title": "网站名称",
              "href": "https://example.com",
              "description": "网站描述",
              "icon": "/assets/favicon.webp",
              "enabled": true
            }
          ]
        }
      ]
    }
  ]
}

🚀 部署指南

Cloudflare Pages 部署（推荐）

创建项目
- 登录 Cloudflare Pages
- 连接 GitHub 仓库
构建设置
# 构建命令 pnpm install && pnpm run cf:build # 输出目录 .next # Node.js 版本 20.0.0
环境变量配置 在 Cloudflare Pages 环境变量中添加所有必需的环境变量
自定义部署
# 本地构建并部署 pnpm run cf:deploy

Vercel 部署

一键部署
- 点击 "Deploy with Vercel" 按钮
- 配置所需的环境变量
手动部署
- Fork 项目到你的 GitHub
- 在 Vercel 中导入项目
- 配置环境变量
- 部署项目

Docker 部署

# 构建镜像
pnpm run docker:build

# 开发环境
pnpm run docker:dev

# 生产环境
pnpm run docker:prod

# 查看日志
pnpm run docker:logs

# 停止服务
pnpm run docker:stop

🔧 开发指南

可用脚本

# 开发模式
pnpm dev

# 构建项目
pnpm build

# 启动生产服务器
pnpm start

# 代码检查
pnpm lint

# 清理构建文件
pnpm clean

# Cloudflare Pages 部署
pnpm run cf:build
pnpm run cf:deploy

# Docker 部署
pnpm run docker:build
pnpm run docker:dev
pnpm run docker:prod

项目结构

vidnav/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API 路由
│   │   │   ├── videos/        # 视频 API
│   │   │   └── navigation/    # 网址导航 API
│   │   ├── admin/             # 管理后台
│   │   │   ├── videos/        # 视频管理
│   │   │   └── navigation/    # 网址管理
│   │   ├── videos/            # 视频页面
│   │   └── components/        # 页面组件
│   ├── components/            # 共享 UI 组件
│   │   ├── video-card.tsx     # 视频卡片
│   │   ├── video-content.tsx  # 视频内容
│   │   ├── video-player-page.tsx # 视频播放器
│   │   ├── navigation-card.tsx # 网址卡片
│   │   └── navigation-content.tsx # 网址内容
│   ├── lib/                   # 工具函数
│   ├── types/                 # TypeScript 类型定义
│   │   ├── navigation.ts      # 导航类型
│   │   └── video.ts          # 视频类型
│   ├── services/              # 服务层
│   └── navsphere/             # 数据文件
│       └── content/
│           ├── videos.json    # 视频数据
│           ├── navigation.json # 网址导航数据
│           └── site.json      # 站点配置
├── public/                    # 静态资源
│   └── assets/
│       ├── cover/             # 视频封面图片
│       └── images/
│           └── logos/         # 网站图标
├── docker/                    # Docker 配置
└── wrangler.toml             # Cloudflare 配置