# mini-nav

**Repository Path**: didiok/mini-nav

## Basic Information

- **Project Name**: mini-nav
- **Description**: https://mini.hello123.com
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://mini.hello123.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

| ![Hello123 预览](./public/img/微信图片_20250818220935.png) |
|:--:|

## Hello123 导航（mini-nav）

一个基于 Next.js App Router、Tailwind CSS、Radix UI/Shadcn UI 构建的极简高性能网址导航站。强调极致加载、移动端友好与 SEO/PWA 完整支持，帮助你快速搭建“上网不迷路”的优质导航站点。

- **在线演示**: [mini.hello123.com](https://mini.hello123.com)
- **GitHub**: [thehello123/hello123](https://github.com/thehello123/hello123)
- **许可证**: MIT（见 `LICENSE`）

### 功能特性

- **导航首页**: 顶部站点信息、搜索头部、左侧分类侧栏、主内容链接区、底部导航、浮动工具栏
- **移动端友好**: 定制断点与容器，底部导航优化小屏体验
- **SEO 完整方案**:
  - 统一 `metadata` 配置（站点标题、描述、关键词、Open Graph、Twitter Cards、Robots）
  - 自动生成 `sitemap`（根据导航分类构建锚点 URL）
  - `StructuredData` 结构化数据，提升搜索引擎理解
- **PWA 支持**: `app/manifest.ts` 定义名称、图标、主题色等
- **主题与字体**: `next-themes` 暗黑模式；字体以系统字体兜底，避免外网依赖
- **UI/交互**: Radix UI 基础组件 + Shadcn UI 封装；自定义对话框、命令面板、Toast
- **链接安全**: `lib/utils/link-security.ts` 提供安全协议检测、受信域名判断与可疑模式识别
- **工程质量**:
  - TypeScript 全量类型
  - ESLint + Prettier + Tailwind 插件
  - TurboPack 开发提速
- **部署友好**: 支持 Vercel 一键部署或 PM2 生产守护（固定端口 3000）

### 技术栈

- **框架**: Next.js 15（App Router）
- **语言**: TypeScript
- **样式**: Tailwind CSS、tailwind-merge、tailwindcss-animate
- **组件**: Radix UI、Shadcn UI、lucide-react
- **状态**: Zustand
- **动画**: framer-motion
- **主题**: next-themes

### 目录结构（关键路径）

```
app/
  layout.tsx           # 应用根布局与全局 metadata、SEO、结构化数据、主题注入
  page.tsx             # 导航首页
  manifest.ts          # PWA Manifest
  sitemap.ts           # 站点地图
components/
  bottom-navigation/   # 底部导航与弹窗
  site-header/         # 顶部导航/主题切换/设定
  ui/                  # Shadcn UI 封装组件
  ...
config/
  site.ts              # 站点信息与导航数据（NavData）
contexts/
  dialog-context.tsx   # 对话框上下文
docs/
  z-index-management.md# 层级管理说明
lib/
  fonts.ts             # 字体策略（系统字体兜底）
  utils.ts             # 工具函数 cn()
  utils/link-security.ts # 外链安全策略
  ...
public/                # 站点图片与图标
styles/
  globals.css          # Tailwind 全局样式
  tab-styles.css       # 自定义 tab 与布局样式
```

### 环境要求

- **Node.js** ≥ 18.18（Next.js 15 推荐）
- **包管理器**: pnpm 9（项目声明为 `pnpm@9.12.1`），或 npm（任选一种，建议 pnpm）
- **固定端口**: 3000（开发与生产统一使用 3000）

### 快速开始（本地开发）

使用 pnpm：

```bash
pnpm install
pnpm dev
# 以 TurboPack 启动开发服务，默认端口 3000
```

使用 npm：

```bash
npm install
npm run dev
# Windows PowerShell 不支持用 && 连接命令；逐条执行即可
```

访问: `http://localhost:3000`

### 构建与运行

使用 pnpm：

```bash
pnpm build
pnpm start
# 在 Windows PowerShell 指定端口：
# $env:PORT=3000; pnpm start
```

使用 npm：

```bash
npm run build
# Windows PowerShell 指定端口：
# $env:PORT=3000; npm run start
```

注意
- 本项目统一使用 3000 端口；不要改为其他端口。
- `mini-nav-build-temp.sh` 示例里存在 4000 端口用法，这是临时脚本示例，生产请统一按 3000 执行。

### 生产部署

#### 方案一：Vercel（推荐）

- 直接导入仓库，一键部署。
- 构建命令：`next build`
- 运行命令：`next start`
- 环境变量：如需自定义 `PORT`，请保持 3000；通常不需要手动设置。

#### 方案二：PM2（服务器）

1) 配置 PM2 进程
- 使用已有 `ecosystem.config.js`，核心设置：
  - `name: "mini_nav"`
  - `cwd: "/root/mini-nav"`
  - `script: "npm"`
  - `args: "run start"`
  - `env.PORT = 3000`

2) 部署脚本（Linux）
可参考 `mini-nav-build.sh`（已固定 3000 端口）：

```bash
pm2 stop mini_nav
pm2 delete mini_nav
npm install
npm run build
pm2 start "PORT=3000 npm run start" --name "mini_nav"
pm2 list
```

提示
- 首次部署前准备：
  - Node.js 18+、PM2 全局安装（`npm i -g pm2`）
  - 服务器需放行 3000 端口（仅对内或经反向代理暴露）
- 生产环境不建议开启 `watch`

### 配置与自定义

- **站点信息与导航数据**: `config/site.ts`
  - 基础信息：`siteConfig.name`、`siteConfig.description`
  - 导航数据：`NavData`（按分类组织，每个条目含 `icon/title/link/desc`）
- **SEO 设置**: `app/layout.tsx` 内 `metadata`
  - 含 `openGraph`、`twitter`、`robots`、`verification`、`other`（AdSense）
- **站点地图**: `app/sitemap.ts`（基于 `NavData` 自动生成锚点 URL）
- **PWA**: `app/manifest.ts`（名称、图标、主题色、分类等）
- **主题与字体**: `components/theme-provider.tsx` + `lib/fonts.ts`
- **样式**: `styles/globals.css`、`tailwind.config.ts`
  - `tailwind.config.ts` 自定义断点与容器宽度、z-index 分层，对应 `docs/z-index-management.md`
- **远程图片**: `next.config.ts` 中 `images.remotePatterns` 允许 https 任意域；生产建议收敛到白名单

### 安全与合规

- **外链安全策略**: `lib/utils/link-security.ts`
  - 检查协议（https/mailto）
  - 校验受信域名（`TRUSTED_DOMAINS`）
  - 可疑模式检测（重定向参数/短链/敏感子域等）
  - 自动生成安全 `rel` 属性与点击确认提示
- **依赖与日志**:
  - 生产构建启用 `compiler.removeConsole: true`
  - PM2 分离标准输出与错误日志，便于追踪

### 开发规范与脚本

- **代码风格**: TypeScript 优先、函数式风格、具名导出
- **Lint/格式化**：

```bash
pnpm lint
pnpm lint:fix
pnpm format:check
pnpm format:write
pnpm typecheck
```

### 常见问题 FAQ

- **“use client” 与 metadata 同文件冲突？**
  - 不能。`metadata` 仅能在服务器组件里导出；添加 `"use client"` 后请将 `metadata` 上移到父级服务器组件或拆分文件。

- **Windows PowerShell 里多个命令如何串行执行？**
  - PowerShell 不支持 `&&`。请逐条执行，或使用 `;` 分隔（注意与 Bash 语法区别）。

- **为什么强制使用 3000 端口？**
  - 为对齐本项目开发与生产环境、脚本与反代配置，统一约定端口 3000，避免环境不一致造成的连通性与监控问题。

### 贡献

欢迎提 Issues/PR，一起完善导航数据与交互体验。提交前请运行：

```bash
pnpm typecheck && pnpm lint && pnpm format:check
```

### 许可证

本项目使用 MIT 许可证，详见 `LICENSE`。