基于 Nuxt 4 + Vue 3 构建的前端 SPA 应用，通过 API 与 Django Ninja 后端服务交互。

• 前后端分离 - 纯前端 SPA 应用，通过 API 调用 Django 后端
• Django Ninja API - 与 Django Ninja 构建的 RESTful API 服务交互
• Nuxt 4 - 现代化全栈 Vue 框架，支持 SSG 静态部署
• Vue 3 - 响应式前端框架，提供优秀的用户体验
• 静态部署 - 生成纯静态文件，可部署到任何 CDN 或静态托管服务
• API 集成 - 内置 HTTP 客户端，轻松调用后端 API 接口
• 文档路由系统 - 基于文件系统的 Markdown 文档路由，支持动态加载
• 简单 Markdown 渲染 - 轻量级渲染器，支持标签和基本 Markdown 语法

zhenxijs-fontend-vue/
├── .cnb.yml            # CNB 构建配置
├── .env.example        # 环境变量示例
├── .gitignore          # Git 忽略文件
├── .install_claude.sh  # Claude安装脚本
├── IFLOW.md            # 项目流程文档
├── app.vue             # 根组件
├── nuxt.config.ts      # Nuxt 配置文件
├── package.json        # 项目依赖配置
├── package-lock.json   # 依赖锁定文件
├── performance-test.js  # 性能测试脚本
├── README.md           # 项目说明文档
├── seo-check.js        # SEO 检测脚本
├── assets/             # 静态资源文件
│   ├── logo.svg        # 项目 Logo
│   └── reset.css       # 全局CSS重置
├── components/         # 公共组件
│   ├── PublicFooter.vue # 公共底部
│   ├── PublicHeader.vue # 公共头部
│   └── SearchBox.vue   # 搜索框组件
├── composables/        # 组合式函数
│   └── useSearch.js    # 搜索功能
├── markdow/            # 简单 Markdown 渲染器
│   ├── README.md       # Markdown 渲染器说明
│   ├── components/     # 组件
│   │   └── ObsidianRenderer.vue
│   └── utils/          # 工具函数
│       └── obsidian-parser.ts
├── pages/              # 页面路由
│   ├── docs/           # 文档路由
│   │   ├── [...slug].vue # 动态文档路由
│   │   └── index.vue   # 文档列表页面
│   ├── index.vue       # 首页
│   ├── schema-demo.vue # Schema演示页面
│   └── seo-test.vue    # SEO 测试页面
└── public/             # 静态文件
    └── docs/           # Markdown文档
        ├── index.md
        └── JavaScript教程.md

• 框架: Nuxt 4.0.3 + Vue 3.5.18
• 构建工具: Vite 7.1.1
• 运行时: Node.js 22+
• 包管理: npm 10+
• 部署: 静态站点生成 (SSG)

# 安装项目依赖
npm ci

# 或使用 npm install
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview

# 生成静态站点
npm run generate

# 运行 SEO 检测
npm run seo

• 前端: Nuxt 4 + Vue 3 SPA 应用（本项目）
• 后端: Django + Django Ninja API 服务
• 通信: RESTful API 接口调用
• 部署: 前后端独立部署，通过 API 通信

1. 环境变量配置

   # .env
   NUXT_PUBLIC_API_BASE=http://localhost:8000/api
   

2. API 客户端配置

   // nuxt.config.ts
   export default defineNuxtConfig({
     runtimeConfig: {
       public: {
         apiBase: process.env.NUXT_PUBLIC_API_BASE || 'http://localhost:8000/api'
       }
     }
   })
   

3. API 调用示例

   <script setup>
   const { data } = await $fetch('/users', {
     baseURL: useRuntimeConfig().public.apiBase
   })
   </script>
   

构建后可部署到任何静态托管服务：

# 构建静态文件
npm run build

# 预览静态站点
npx serve .output/public

生成的静态文件可部署到：

• Vercel / Netlify
• GitHub Pages
• 阿里云 OSS / 腾讯云 COS。EdgeOne Page
• Nginx 静态服务器

项目内置完整的 SEO 优化：

• 完整 TDK: Title、Description、Keywords 完整配置
• Open Graph: 社交媒体分享优化（Facebook、LinkedIn 等）
• Twitter Card: Twitter 分享卡片优化
• 结构化数据: 搜索引擎友好的 HTML 结构
• 静态预渲染: 搜索引擎可直接抓取完整内容

<script setup>
useSeoMeta({
  title: '页面标题 - 网站名称',
  description: '详细的页面描述，包含关键词和核心信息',
  keywords: 'Vue3, Nuxt4, Django, API, 关键词1, 关键词2',
  author: 'ZhenxiJS',
  robots: 'index,follow',
  
  // Open Graph 标签
  ogTitle: '社交媒体标题',
  ogDescription: '社交媒体描述',
  ogType: 'website',
  ogUrl: '/page-url',
  ogImage: '/og-image.jpg',
  ogSiteName: '网站名称',
  
  // Twitter Card 标签
  twitterCard: 'summary_large_image',
  twitterTitle: 'Twitter 标题',
  twitterDescription: 'Twitter 描述',
  twitterImage: '/twitter-image.jpg'
})

// 设置页面语言和其他属性
useHead({
  htmlAttrs: {
    lang: 'zh-CN'
  },
  meta: [
    { name: 'format-detection', content: 'telephone=no' },
    { name: 'theme-color', content: '#00DC82' }
  ]
})
</script>

• 文件合并: JavaScript 代码合并为 2 个主要文件，减少 HTTP 请求
• 代码分割优化: vendor 和 main 代码分离，提升缓存效率
• CSS 优化: 自动压缩和优化 CSS 文件
• 资源内联: SVG 图片内联到 HTML，减少网络请求
• 预加载优化: 关键资源预加载，提升首屏速度

# 运行 SEO 质量检测
npm run seo

# 检测内容包括：
# - 页面标题和描述
# - 关键词密度
# - 图片 alt 属性
# - 链接结构
# - 页面加载速度

export default defineNuxtConfig({
  ssr: true,          // 构建时预渲染 HTML（SSG 必需），生成包含完整内容的静态文件
  nitro: {
    preset: "static", // 静态文件生成模式
    prerender: {
      routes: ["/", "/about"]   // 需要预渲染的页面路由
    }
  },
  // 优化 SEO 和静态生成
  experimental: {
    payloadExtraction: false  // 禁用 payload 提取，减少文件分割
  },
  // 减少 JavaScript 分割，提升 SEO
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: (id) => {
            // 将所有代码打包到一个文件中，减少文件分割
            if (id.includes('node_modules')) {
              return 'vendor'
            }
            return 'main'
          }
        }
      }
    }
  },
  // 优化 HTML 输出
  app: {
    head: {
      charset: 'utf-8',
      viewport: 'width=device-width, initial-scale=1'
    }
  }
})

重要: 项目使用 SSG (静态站点生成) 模式，不是传统的 SSR：

• ssr: true: 在构建时预渲染 HTML，生成包含完整内容的静态文件
• ssr: false: 生成 SPA 模式，HTML 中只有空的 <div>，内容需 JavaScript 渲染

为什么需要 ssr: true：

1. SEO 友好 - 搜索引擎可直接读取 HTML 中的完整内容
2. 完整 TDK - Title、Description、Keywords 预渲染到 HTML
3. 首屏速度 - 用户立即看到内容，无需等待 JavaScript
4. 社交分享 - Open Graph 和 Twitter Card 元数据完整

最终产物: 纯静态文件 + Vue 交互功能，无需服务器运行。

• API 优先: 所有数据交互通过 Django Ninja API 接口
• Vue 3 Composition API: 使用现代化的 Vue 3 语法
• 组件化开发: 页面拆分为可复用的 Vue 组件
• 状态管理: 使用 Pinia 或 Vuex 管理应用状态
• 类型安全: 定义 API 接口的 TypeScript 类型

1. 本地开发

   npm run dev    # 启动前端开发服务器 (http://localhost:3000)
   

2. API 联调

   • 确保 Django 后端服务运行在 http://localhost:8000
   • 配置 API 基础地址环境变量
   • 测试 API 接口调用

3. 构建部署

   npm run generate  # 推荐：生成优化的静态文件（SSG）
   npm run build     # 或者：标准构建
   npm run seo       # 检测页面 SEO 质量
   

命令	用途	输出	推荐场景
npm run generate	SSG 静态生成	完整预渲染的 HTML	推荐，SEO 友好
npm run build	标准构建	服务端渲染模式	需要服务器部署时

项目集成了基于文件系统的文档路由系统，可以轻松地通过 URL 访问 public/docs 目录下的 Markdown 文档。

public/docs/           → 页面路由
├── index.md          → /docs 或 /docs/index
└── JavaScript教程.md  → /docs/JavaScript教程

• /docs - 文档列表页面，显示所有可用文档
• /docs/index - 渲染 public/docs/index.md 文件
• /docs/JavaScript教程 - 渲染 public/docs/JavaScript教程.md 文件
• /docs/任意路径 - 尝试渲染 public/docs/任意路径.md 文件

• 动态路由: 支持任意层级的文档路径
• 自动加载: 从 public/docs 目录自动加载 .md 文件
• 标签支持: Markdown 中的 #标签 会被渲染为可点击元素
• 错误处理: 文件不存在时显示友好的错误信息
• 响应式设计: 适配不同屏幕尺寸

1. 访问文档列表: 浏览器访问 /docs
2. 查看具体文档: 点击文档卡片或直接访问 /docs/JavaScript教程
3. 标签交互: 在文档中点击 #标签 触发标签点击事件

• 标签支持: #标签 语法，标签会被渲染为可点击的元素
• 基础 Markdown: 支持标准的 Markdown 语法（标题、段落、列表、粗体、斜体、代码、链接、表格、引用块、代码块）
• 链接 SEO 优化: 自动为外部链接添加 nofollow 属性
• 不支持的语法: 双向链接 [[文件名]] 会被视为普通文本

• ✅ 文件合并: 从多个 JS 文件合并为 2 个主要文件
• ✅ 体积优化: 主应用 172KB，辅助代码 5.8KB
• ✅ 加载优化: 减少 HTTP 请求，提升首屏速度
• ✅ 缓存友好: vendor 和 main 分离，提升缓存效率

• ✅ 完整 TDK: 每个页面都有标题、描述、关键词
• ✅ 结构化内容: HTML 中包含完整页面内容
• ✅ 社交分享: Open Graph 和 Twitter Card 完整配置
• ✅ 搜索引擎友好: 支持直接抓取，无需 JavaScript 渲染

• ✅ 纯静态文件: 可部署到任何 CDN 或静态托管
• ✅ 前后端分离: 独立部署，通过 API 通信
• ✅ Vue 交互: 保留完整的 SPA 功能
• ✅ 跨平台兼容: 支持各种静态托管服务

如遇到 API 请求错误，请检查：

1. Django 后端服务是否正常运行
2. API 基础地址配置是否正确
3. CORS 跨域设置是否配置（Django 端）
4. API 接口路径和参数是否正确

本地开发时的注意事项：

1. 确保前后端端口不冲突（前端 3000，后端 8000）
2. 检查环境变量 .env 文件配置
3. 确认 Django Ninja API 文档可访问

静态部署时可能遇到的问题：

1. API 地址需要配置为生产环境地址
2. 检查静态资源路径是否正确
3. 确认 CDN 或静态托管服务配置

ISC License

欢迎提交 Issue 和 Pull Request 来改进项目。

---

项目用途: Django 后台前端页面生成
开发团队: ZhenxiJS
项目版本: 1.0.0
最后更新: 2025年8月