NavBook 航书

Appearance

开发指南 ​

开发环境搭建 ​

系统要求 ​

  • 操作系统: macOS / Windows / Linux
  • Node.js: >= 18.0.0
  • 包管理器: npm >= 9.0.0 或 pnpm >= 8.0.0
  • Git: >= 2.30.0

推荐工具 ​

  • IDE: VSCode / WebStorm
  • 浏览器: Chrome / Edge / Safari（最新版）
  • VSCode 插件: Vue Language Features (Volar)、TypeScript Vue Plugin、Prettier

项目架构 ​

技术栈 ​

层级技术
前端框架Vue 3 + TypeScript
状态管理Pinia
路由Vue Router
UI 组件Ant Design Vue + @gitcoffee/design-ui
构建工具Vite
国际化vue-i18n
图标@gitcoffee/icons

目录结构 ​

navbook/
├── public/                     # 静态资源
│   ├── favicon.svg            # 网站图标
│   └── logo.svg               # Logo
├── src/                        # 源代码
│   ├── locales/               # 国际化文件
│   │   ├── en/                # 英文
│   │   │   └── common.json
│   │   ├── zh/                # 简体中文
│   │   │   └── common.json
│   │   ├── zh-TW/             # 繁体中文
│   │   │   └── common.json
│   │   └── index.ts           # i18n 入口
│   ├── router/                # 路由配置
│   │   └── index.ts
│   ├── stores/                # Pinia 状态管理
│   │   └── navbook.ts
│   ├── views/                 # 页面视图
│   │   ├── HomeView.vue
│   │   ├── UrlView.vue
│   │   ├── SocialMediaView.vue
│   │   ├── QRCodeView.vue
│   │   ├── WechatView.vue
│   │   ├── BookmarkView.vue
│   │   ├── AIResourceView.vue
│   │   ├── MCPView.vue
│   │   ├── CLIView.vue
│   │   ├── SkillView.vue
│   │   ├── AgentView.vue
│   │   ├── SettingView.vue
│   │   └── NotFoundView.vue
│   ├── App.vue                # 根组件
│   ├── main.ts                # 入口文件
│   └── vite-env.d.ts          # 类型声明
├── index.html                 # HTML 模板
├── package.json               # 项目配置
├── tsconfig.json              # TypeScript 配置
├── tsconfig.node.json         # Node TypeScript 配置
└── vite.config.ts             # Vite 配置

开发规范 ​

代码规范 ​

  • 使用 Prettier 进行代码格式化
  • 遵循 Vue 3 组合式 API 风格
  • TypeScript 严格模式启用
  • 组件命名使用 PascalCase
  • 函数命名使用 camelCase

Git 规范 ​

类型(scope): 简短描述

详细描述（可选）

Footer（可选）

类型说明：

  • feat: 新功能
  • fix: 修复
  • docs: 文档
  • style: 格式
  • refactor: 重构
  • perf: 性能优化
  • test: 测试
  • chore: 构建/工具

示例：

feat(url): 添加网址自动抓取功能

- 支持自动抓取网站标题
- 支持自动抓取网站图标
- 支持自动抓取网站描述

Closes #123

分支管理 ​

  • main: 主分支，稳定版本
  • develop: 开发分支
  • feature/*: 功能分支
  • hotfix/*: 紧急修复
  • release/*: 发布分支

模块开发 ​

页面开发 ​

vue
<template>
  <div class="nav-view">
    <a-page-header :title="t('nav.title')">
      <template #extra>
        <a-button type="primary" @click="handleAdd">
          {{ t('nav.add') }}
        </a-button>
      </template>
    </a-page-header>
    <ResourceList
      :resources="resources"
      @load-more="loadMore"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useI18n } from 'vue-i18n'
import { useNavbookStore } from '~/stores/navbook'

const { t } = useI18n()
const store = useNavbookStore()
const resources = ref<Resource[]>([])

onMounted(async () => {
  await store.loadResources()
  resources.value = store.resources
})

const handleAdd = () => {
  // 添加资源逻辑
}
</script>

状态管理 ​

typescript
// stores/navbook.ts
import { defineStore } from 'pinia'

export const useNavbookStore = defineStore('navbook', {
  state: () => ({
    resources: [] as Resource[],
    settings: {
      theme: 'auto' as 'light' | 'dark' | 'auto',
      language: 'zh',
    },
  }),
  getters: {
    isDarkMode: (state) => state.settings.theme === 'dark',
  },
  actions: {
    async loadResources() {
      // 加载资源逻辑
    },
  },
})

国际化 ​

json
// locales/zh/common.json
{
  "nav": {
    "title": "导航",
    "add": "添加",
    "search": "搜索"
  }
}
typescript
// 在组件中使用
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
console.log(t('nav.title'))

调试技巧 ​

浏览器调试 ​

  1. Vue DevTools: 安装浏览器扩展，查看组件树和状态
  2. Network: 查看 API 请求和响应
  3. Console: 查看日志输出

构建调试 ​

bash
# 开发模式（含 sourcemap）
npm run dev

# 快速构建（无压缩）
npm run build:fast

性能优化 ​

前端优化 ​

  1. 路由懒加载: 大型视图组件使用动态导入
  2. 图片懒加载: 图片进入视口才加载
  3. 资源分页: 大量资源分页加载
  4. 代码分割: Vite 自动进行代码分割

构建优化 ​

  1. 手动分包: 在 vite.config.ts 中配置 manualChunks
  2. Tree Shaking: 确保使用 ES Module 导入
  3. 资源压缩: 生产构建启用 esbuild 压缩

部署 ​

静态部署 ​

bash
# 构建
npm run build

# 部署 dist 目录到任意静态服务器

Docker 部署 ​

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

# 运行容器
docker run -d -p 80:80 navbook:latest

Nginx 配置 ​

nginx
server {
    listen 80;
    server_name navbook.example.com;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://backend:8080;
    }
}

常见问题 ​

Q: 开发服务器启动失败？ ​

A: 检查：

  1. Node.js 版本是否 >= 18
  2. 端口 5174 是否被占用
  3. 依赖是否安装完整

Q: 构建报错？ ​

A: 检查：

  1. TypeScript 类型是否正确
  2. 导入路径是否使用 ~ 别名
  3. 依赖版本是否兼容

Q: 主题切换不生效？ ​

A: 检查：

  1. 浏览器是否支持 prefers-color-scheme
  2. CSS 变量是否正确覆盖
  3. Ant Design Vue 主题配置是否同步

相关资源 ​