在h3中实现静态资源服务与SPA路由回退方案

h3是一个轻量级的Node.js HTTP框架，它提供了简洁的API来处理HTTP请求。本文将介绍如何使用h3框架实现静态资源服务，并针对单页应用(SPA)实现路由回退到index.html的功能。

静态资源服务基础实现

h3框架提供了serveStatic中间件来处理静态文件服务。基本实现如下：

import { createApp, defineEventHandler, serveStatic } from "h3";
import { stat, readFile } from "node:fs/promises";
import { join } from "pathe";

const app = createApp();
const publicDir = "public";

app.use(
  defineEventHandler((event) => {
    return serveStatic(event, {
      getContents: (id) => readFile(join(publicDir, id)),
      getMeta: async (id) => {
        const stats = await stat(join(publicDir, id)).catch(() => {});
        
        if (!stats || !stats.isFile()) {
          return;
        }

        return {
          size: stats.size,
          mtime: stats.mtimeMs,
        };
      },
    });
  }),
);

这段代码创建了一个基本的静态文件服务器，它会：

1. 从指定的public目录读取文件
2. 检查文件是否存在及是否为有效文件
3. 返回文件内容和元数据

实现SPA路由回退

对于单页应用(SPA)，当用户直接访问某个路由或刷新页面时，我们需要确保服务器能回退到index.html，让前端路由接管后续处理。以下是改进后的实现：

app.use(
  defineEventHandler(async (event) => {
    const result = await serveStatic(event, {
      fallthrough: true,  // 关键参数，允许中间件继续执行
      getContents: (id) => readFile(join(publicDir, id)),
      getMeta: async (id) => {
        const stats = await stat(join(publicDir, id)).catch(() => {});
        
        if (!stats || !stats.isFile()) {
          return;
        }

        return {
          size: stats.size,
          mtime: stats.mtimeMs,
        };
      },
    });

    if (result === false) {
      // 当静态文件未找到时，返回index.html
      return readFile(join(publicDir, "index.html"), "utf8");
    }
  }),
);

关键改进点：

1. 添加了fallthrough: true选项，使得当静态文件不存在时不会直接返回404
2. 检查serveStatic的返回值，如果是false则返回index.html
3. 使用异步处理确保流程正确

实现原理分析

这种实现方式利用了h3中间件的特性：

1. serveStatic会尝试匹配请求路径对应的静态文件
2. 当fallthrough为true且文件不存在时，返回false而非直接响应
3. 我们可以根据返回值决定后续处理逻辑
4. 对于不存在的路由，返回index.html让前端路由处理

性能考虑

在实际生产环境中，还需要考虑以下优化点：

1. 添加缓存控制头，提高静态资源加载性能
2. 对index.html文件设置较短的缓存时间或不缓存
3. 考虑使用ETag或Last-Modified进行条件请求处理
4. 对于大型项目，可能需要引入更专业的静态文件服务中间件

这种实现方式特别适合现代前端框架(如Vue、React等)构建的单页应用部署场景，确保了前端路由能正常工作，同时保持了静态资源的高效服务。