Vue 3 + TypeScript + Vite 服务端渲染项目

Vue 3 + TypeScript + Vite 服务端渲染项目

项目简介

这是一个基于 Vue 3、TypeScript 和 Vite 构建的现代化前端项目,同时支持服务端渲染 (SSR) 和客户端渲染 (CSR) 两种模式。项目展示了如何在 Vue 3 应用中实现完整的 SSR 功能,包括数据预取、元信息管理和服务端渲染管道。

技术栈

  • 前端框架: Vue 3 (Composition API)
  • 编程语言: TypeScript
  • 构建工具: Vite 7.x
  • 路由管理: Vue Router 4
  • 运行时环境: Bun
  • 服务端渲染: Vue SSR

项目结构

perl 复制代码
h5/
├── src/                   # 源代码目录
│   ├── assets/            # 静态资源文件
│   ├── page/              # 页面组件
│   ├── use/               # 自定义 hooks
│   ├── app.ts             # 应用创建逻辑
│   ├── main.ts            # 客户端入口文件
│   └── server.ts          # SSR 渲染逻辑
├── server.ts              # 服务端入口文件 (Bun 服务器)
├── vite.config.ts         # Vite 配置
├── package.json           # 项目配置和依赖
└── index.html             # HTML 入口文件

核心功能模块

1. 应用创建与路由管理 (app.ts)

该模块负责创建 Vue 应用实例并配置路由系统,同时支持 SSR 和 CSR 两种模式。

主要功能:

  • 创建支持 SSR 的 Vue 应用实例
  • 配置路由规则和组件懒加载
  • 根据环境选择合适的路由历史模式
typescript 复制代码
// src/app.ts
import { createSSRApp } from 'vue'
import App from './App.vue'
import { createRouter, createMemoryHistory, createWebHistory } from 'vue-router'

export function createApp(ssr: boolean = false) {
  const app = createSSRApp(App)
  const routes = [
    { path: '/', component: () => import('./page/home.vue'), meta: { title: 'home' } },
    { path: '/about', component: () => import('./page/about.vue'), meta: { title: 'about' } },
  ]

  const router = createRouter({
    history: ssr ? createMemoryHistory() : createWebHistory(),
    routes,
  })

  app.use(router)
  return { app, router }
}

2. 页面元信息管理 (use/head.ts)

自定义 hook 用于管理页面标题、关键词和描述等元信息,同时支持 SSR 和 CSR 环境。

主要功能:

  • 统一管理页面元数据
  • 在客户端环境中自动更新 DOM
  • 支持 SSR 上下文传递元数据
typescript 复制代码
// src/use/head.ts
import { ref, type Ref, onMounted } from 'vue'

type HeadType = {
  title: string,
  keyword: string,
  description: string
}

export const head: Ref<HeadType> = ref({
  title: '',
  keyword: '',
  description: ''
})

export function useHead(init: HeadType) {
  // 在服务器端和客户端都设置head数据
  head.value = init
  
  // 只在客户端环境中操作DOM
  onMounted(() => {
    try {
      if (document.title !== init.title) {
        document.title = init.title
        document.head.querySelector('meta[name="keyword"]')?.setAttribute('content', init.keyword)
        document.head.querySelector('meta[name="description"]')?.setAttribute('content', init.description)
      }
    } catch (e) {
      console.log(e)
    }
  })
}

3. 服务端渲染实现 (src/server.ts & server.ts)

项目实现了完整的 SSR 渲染流程,包括路由预解析、组件渲染和 HTML 拼接。

主要功能:

  • 创建 SSR 模式的应用实例
  • 处理 URL 请求和路由跳转
  • 预加载路由组件
  • 渲染应用为 HTML 字符串
  • 传递元数据到客户端
typescript 复制代码
// src/server.ts
import { renderToString } from '@vue/server-renderer'
import { createApp } from './app'
import { head } from './use/head'

export async function render(url: string) {
  const { app, router } = createApp(true)
  const ctx = { 'head': head.value }
  router.push(url)
  await router.isReady()
  const html = await renderToString(app, ctx)
  return { html, ctx }
}

// server.ts (Bun服务器)
import { serve, file } from 'bun'

serve({
  port: 3000,
  async fetch(req) {
    let url = new URL(req.url)
    // 处理静态资源
    if (url.pathname.startsWith('/assets')) {
      // 静态资源处理逻辑...
    }
    // 渲染Vue应用
    const render = (await import('./dist/server/server.js')).render
    const html = await file('./dist/client/index.html').text()
    const rendered = await render(url.pathname)
    return new Response(
      html
        .replace('<!--app-html-->', rendered.html)
        .replace('<!--app-head-html-->', rendered.ctx.head.title)
        .replace('<!--app-head-keyword-->', rendered.ctx.head.keyword)
        .replace('<!--app-head-description-->', rendered.ctx.head.description),
      {
        headers: { 'Content-Type': 'text/html' }
      }
    )
  }
})

4. 页面组件实现

项目包含两个主要页面组件:首页和关于页面,均实现了 SSR 环境下的数据预取。

核心特性:

  • 使用 onServerPrefetch 确保在 SSR 环境中预取数据
  • 集中管理页面元信息设置
  • 组件懒加载优化性能
typescript 复制代码
// 页面组件示例 (home.vue)
<script lang="ts" setup>
import { onServerPrefetch } from 'vue'
import { useHead } from '../use/head'

const init = () => {
  useHead({
    title: '关于我们-ssr,全栈框架',
    keyword: '关于我们,ssr,全栈框架',
    description: '关于我们-ssr,全栈框架'
  })
}

// 在客户端和服务端都执行
init()

// 仅在服务端渲染时执行,确保元信息正确设置
onServerPrefetch(() => {
  init()
})
</script>

构建与运行脚本

项目提供了以下 npm 脚本用于开发和构建:

bash 复制代码
# 开发模式(CSR)
npm run dev

# 服务端渲染构建和运行
npm run ssr

# 构建生产版本
npm run build

# 预览生产构建结果
npm run preview

Vite 配置

项目的 Vite 配置支持 SSR 模式,并设置了一些优化选项:

typescript 复制代码
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  ssr: {
    noExternal: ['vue']  // 确保 Vue 在 SSR 构建中被正确处理
  },
  build: {
    assetsInlineLimit: 0  // 禁用资源内联
  }
})

客户端入口 (main.ts)

客户端入口文件负责创建 Vue 应用实例并挂载到 DOM 上:

typescript 复制代码
// src/main.ts
import { createApp } from './app'

const { app } = createApp()
app.mount('#app')

开发注意事项

  1. SSR 环境下的数据预取

    • 使用 onServerPrefetch 钩子确保在服务器端正确预取数据
    • 确保组件中的 DOM 操作仅在客户端执行
  2. 元信息管理

    • 使用 useHead hook 统一管理页面元信息
    • 服务端会将元信息传递给客户端,确保 SEO 友好
  3. 注意事项(发现的问题)

    • home.vueabout.vue 中存在标题设置错误:首页组件设置了"关于我们"的标题,而关于页面设置了"首页"的标题
    • 需要修正这两个文件中的元信息设置,确保标题与页面内容一致

技术亮点

  1. 完整的 SSR 实现:项目展示了 Vue 3 中完整的服务端渲染实现,包括路由预解析、数据预取和 HTML 渲染

  2. 统一的元信息管理:通过自定义 hook 实现了 SSR 和 CSR 环境下的元信息统一管理

  3. 基于 Bun 的服务端:使用现代的 Bun 运行时作为服务端环境,提升性能

  4. 组件懒加载:路由组件使用动态导入实现懒加载,优化初始加载性能

部署说明

  1. 安装依赖

    bash 复制代码
    bun install
  2. 构建项目

    bash 复制代码
    bun run build
  3. 服务端渲染部署

    bash 复制代码
    bun run ssr
  4. 访问应用 打开浏览器访问 http://localhost:3000

相关推荐
闲不住的李先森3 天前
AI 基础调用实现:从原理到代码实现
前端·llm·全栈
EndingCoder6 天前
React 19 与 Next.js:利用最新 React 功能
前端·javascript·后端·react.js·前端框架·全栈·next.js
梦想CAD控件7 天前
(在线CAD插件)网页CAD实现图纸表格智能提取
前端·javascript·全栈
susnm8 天前
最后的最后
rust·全栈
章丸丸9 天前
Tube - tRPC setup
react native·全栈
JefferyXZF10 天前
Next.js Server Actions 详解: 无缝衔接前后端的革命性技术(八)
前端·全栈·next.js
CF14年老兵11 天前
🤯 AI写代码比人类便宜99.9%!但这就是真相吗?
openai·全栈·trae
滕本尊12 天前
从业务到框架:Elpis 企业级应用的 NPM 包抽离实践
前端·全栈
EndingCoder12 天前
测试 Next.js 应用:工具与策略
开发语言·前端·javascript·log4j·测试·全栈·next.js