基于 Vite 的全栈框架工作原理

// app/routes.ts —— 显式配置
import { type RouteConfig, index, route } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),                        // /
  route('blog/:slug', 'routes/blog.$slug.tsx', [   // /blog/:slug
    index('routes/blog.index.tsx'),
  ]),
] satisfies RouteConfig;

src/routes/
├── page.tsx                 →  /
├── blog/
│   ├── page.tsx             →  /blog
│   └── [slug]/
│       └── page.tsx         →  /blog/:slug
└── (marketing)/             →  路由组：只分组，不产生路径段
    └── about/page.tsx       →  /about

// 框架插件内部（概念伪代码）
function resolveRoutes() {
  if (config.style === 'file') {
    // 文件路由：扫描目录，把文件名编译成路由模式
    return scanDir('src/routes').map(file => ({
      pattern: filenameToPattern(file),  // blog/[slug]/page.tsx → '/blog/:slug'
      module: () => import(file),        // 懒加载路由组件
    }));
  }
  // 配置路由：直接读取用户配置
  return loadConfig('app/routes.ts');
}

// 注册虚拟模块，业务侧统一 import { routes } from 'virtual:framework/routes'

// 路由匹配：模式 → 正则，逐层匹配 URL
const compiled = routes.map(r => ({
  ...r,
  regex: compilePattern(r.pattern),  // '/blog/:slug' → /^\/blog\/([^/]+)$/
}));

function matchRoutes(pathname: string) {
  for (const r of compiled) {
    const m = pathname.match(r.regex);
    if (m) return { route: r, params: extractParams(r, m) };
    //                       → { slug: 'hello' }
  }
  return null; // 404
}

// 概念伪代码
const vite = await createServer({ appType: 'custom' });

app.use(vite.middlewares);            // 1. Vite 原生：静态资源、HMR
app.use(async (req, res, next) => {   // 2. 框架：接管页面请求
  const build = await vite.ssrLoadModule('virtual:framework/server');
  //      ↑ 按需编译，源码改动即时生效（无全量打包）
  const { routes } = await vite.ssrLoadModule('virtual:framework/routes');
  const match = matchRoutes(req.url);          // ← 第一章的路由匹配在这里发生
  if (!match) return next();                   // 未命中，交给后续中间件
  const data = await runLoaders(match, req);   // 执行 loader 取数
  res.end(renderToHtml(match, data));          // SSR 渲染并返回
});

// vite.config.ts —— 框架插件自动展开为（概念示意）
export default {
  environments: {
    client: { resolve: { conditions: ['browser'] } },
    ssr:    { resolve: { conditions: ['node'] },
              external: ['node:fs', 'node:path'] },  // 服务端依赖不打包
  },
};

if (import.meta.env.SSR) {           // 构建时静态替换为 true/false
  const fs = await import('node:fs'); // 客户端构建中此分支被整体剔除
}

// src/entry-server.tsx —— 框架生成的服务端入口（概念示意）
import { createRequestHandler } from 'framework';

export const handler = createRequestHandler({
  routes,                                     // 第一章：归一化后的路由配置
  runLoaders,                                 // 渲染前服务端取数
  render: (App) => renderToString(<App />),   // SSR 渲染器
  serialize: (data) => inlineScript(data),    // 数据内联进 HTML（供 Hydration）
});
// handler: (Request) => Promise<Response> —— 纯函数，无 IO 副作用

build/server/index.js —— 导出 handler(Request) → Response
   │
   ├── 消费方式一：适配器把它挂到真实服务器
   │     → 每个到达的请求实时渲染 → SSR 部署（本章 4.2）
   │
   └── 消费方式二：构建机的 Node 进程内直接调用
         → 对每个预声明路径渲染一次并保存 → SSG 预渲染（第五章）

// Express 适配器（概念伪代码）
async (req, res) => {
  const request  = new Request(req.url, { method: req.method }); // req → Request
  const response = await handler(request);                       // 调用处理器
  res.status(response.status).send(await response.text());       // Response → res
};

// Cloudflare Workers 适配器：平台原生就是 Fetch API，几乎零转换
export default { fetch: handler };

// 概念伪代码：框架的预渲染器
const serverEntry = await import('./build/server/index.js'); // ← 上一步的产物

for (const path of await getPrerenderPaths()) {   // '/', '/blog/a', '/blog/b'...
  const request  = new Request(`http://localhost${path}`);
  const response = await serverEntry.handler(request); // 与线上完全相同的处理器

  await writeFile(`build/client${path}.html`, await response.text());
  //                          ↑ HTML 快照（含内联的 loader 数据）

  await writeFile(`build/client${path}.data`, serialize(loaderData));
  //                          ↑ 数据快照：客户端导航时 fetch 这个静态文件
}

// 最终产物：纯静态，直接上传 CDN，无需任何服务器

开发编码        文件路由 / 配置路由 / loader / import.meta.env.SSR
   │
pnpm dev        Vite 中间件拦截请求 → 按需编译 → SSR（无打包）
   │
pnpm build      Vite 双构建 → client 产物 + server 产物（请求处理器）
   │
   ├── SSR 部署：适配器桥接 → 挂到 Express / Workers / Serverless
   │
   └── SSG：Node 内模拟请求 → 渲染 HTML + 保存 .data → 纯静态产物

npm create vite@latest my-app -- --template react
npm install react-router-dom        # 路由库：只是一个普通运行时依赖

// src/main.tsx —— 路由在浏览器里由组件树驱动
import { BrowserRouter, Routes, Route } from 'react-router-dom';

createRoot(root).render(
  <BrowserRouter>
    <Routes>
      <Route path="/" element={<Home />} />
      <Route path="/blog/:slug" element={<Blog />} />
    </Routes>
  </BrowserRouter>
);

// vite.config.ts —— 几乎为零配置
export default defineConfig({
  plugins: [react()],
  // appType: 'spa'（默认）：Vite 自带 history fallback
});

SPA 模式：   浏览器 ──请求──► 服务器（只回 index.html）
                              浏览器收到 HTML 后，路由库读取 URL，
                              在客户端切换组件 ← 路由匹配发生在浏览器

全栈框架：   浏览器 ──请求──► 请求处理器（服务端）
                              服务端匹配路由 → 执行 loader → SSR 渲染
                              ← 路由匹配发生在服务器

// SPA：数据获取是渲染之后的事（客户端组件内）
function Blog({ params }) {
  const [post, setPost] = useState(null);
  useEffect(() => {
    fetch(`/api/posts/${params.slug}`)   // 浏览器发起，晚了整个首屏
      .then(r => r.json())
      .then(setPost);
  }, [params.slug]);
}

// 全栈框架：loader 在渲染之前、服务端执行
export async function loader({ params }) {
  return { post: await db.getPost(params.slug) };
}

// SPA 模式下服务器/托管的全部职责（history fallback）
app.use((req, res) => res.sendFile('index.html')); // 不管什么路径，都回壳

Vite + 路由库 ──(需要 SEO/首屏)──► vite-plugin-ssr / vike ──► 全栈框架
                                     (RR v7 / SvelteKit / Nuxt)