使用 vite-plugin-prerender 实现静态预渲染

在开发工具类页面（如 JSON 格式化器、二维码生成器等）时，使用 Vite + Vue 构建是非常高效的。但如果你希望将整个站点部署为 完全静态的页面 并使用 Nginx 托管，你可能会遇到以下几个问题：

• vite build 输出的 HTML 是“壳子”，依赖 JS 才能渲染内容。
• 使用 Nginx 部署后，通过 wget 或搜索引擎访问页面时，看到的仍是空页面。
• 静态资源（如图片）出现 404，或路径错误。

本文将完整介绍如何：

1. 使用 vite-plugin-prerender 实现页面预渲染；
2. 设置 Vite 构建输出路径；
3. 正确配置 Nginx；
4. 处理静态资源路径问题。

📦 项目结构简述

假设你的 Vue 工具项目放在 /tool/ 路由下，构建后你希望路径结构如下：

dist/
└── tool/
    ├── index.html
    ├── paste/index.html
    ├── assets/
    │   └── *.js, *.css
    └── tinyash.webp

⚙️ 1. 安装 vite-plugin-prerender

npm i vite-plugin-prerender --save-dev

⚙️ 2. 配置 vite.config.ts

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import prerender from 'vite-plugin-prerender'
import { resolve } from 'path'

export default defineConfig({
  base: '/tool/', // 所有资源路径前缀
  plugins: [
    vue(),
    prerender({
      staticDir: resolve(__dirname, 'dist'),
      routes: [
        '/tool',
        '/tool/paste',
        '/tool/json-formatter',
        '/tool/uuid'
        // ...列出你所有需要预渲染的页面
      ]
    })
  ],
  build: {
    rollupOptions: {
      output: {
        assetFileNames: 'tool/assets/[name]-[hash][extname]',
      },
    }
  }
})

注意事项：

• base: '/tool/' 必须设置，否则资源路径会错；
• routes 中列出所有需要预渲染的路径；
• assetFileNames 控制打包后静态资源输出到 tool/assets。

🖼️ 3. 处理静态资源路径

若你有 favicon 或图标文件，比如：

<link rel="icon" href="/tool/tinyash.webp">

你需要将 tinyash.webp 放到：

public/tool/tinyash.webp

这样构建时 Vite 会自动复制到：

dist/tool/tinyash.webp

🌐 4. 配置 Nginx

使用 root 而不是 alias 是关键！以下是推荐配置：

server {
    listen 80;
    server_name your-domain.com;

    root /usr/share/nginx/html/dist;

    location ^~ /tool/ {
        index index.html;
        try_files $uri $uri/ /tool/index.html;
    }
}

解释：

• root 指向的是 dist；
• /tool/ 会映射到 dist/tool/；
• try_files 逻辑保证 Vue 路由 fallback 到 index.html；
• 不再使用 alias，避免路径错位。

✅ 验证效果

部署完毕后：

wget http://your-domain.com/tool/paste

你应该能看到完整的 HTML 内容，包含预渲染后的 DOM，而不是空壳！

🧠 常见坑总结

🎉 结语

这套方案让你可以将一个 Vue + Vite 项目部署为纯静态站点，无需 Node 后端支撑，适合用于：

• 工具集合页面
• 个人主页
• 小工具平台

希望对你有帮助！如果你遇到更复杂的预渲染问题（如数据请求、分页），也可以考虑结合 SSR/SSG 框架如 Nuxt、Astro 等。