SSR Stubs 技术详解：优化 Cloudflare Workers 部署的包体积

源代码
   ↓
Vite 构建
   ├── 客户端构建 → 完整库代码
   └── SSR 构建   → stubs 替换重型库
                        ↓
                   生成精简的 SSR bundle

// vite.config.ts
const ssrOnlyStubs = () => ({
  name: 'ssr-only-stubs',
  enforce: 'pre',
  resolveId(id, importer, { ssr }) {
    // 仅在 SSR 构建时生效
    if (!ssr) return null;
    
    // 匹配需要 stub 的库
    if (id === 'beautiful-mermaid') {
      return '\0stub:beautiful-mermaid';
    }
  },
  load(id) {
    if (id === '\0stub:beautiful-mermaid') {
      // 返回空实现
      return 'export default () => {}';
    }
  }
});

const ssrOnlyStubs = () => ({
  name: 'ssr-only-stubs',
  enforce: 'pre',
  resolveId(id, importer, { ssr }) {
    if (!ssr) return null;
    
    // Mermaid 相关库 - 客户端渲染图表
    if (id.includes('beautiful-mermaid') || 
        id.includes('@streamdown/')) {
      return '\0stub:noop';
    }
    
    // Shiki 语言定义 - 客户端代码高亮
    if (id.includes('shiki/langs/')) {
      return '\0stub:empty-array';
    }
    
    // WASM 引擎 - Workers 不兼容
    if (id.includes('@shikijs/engine-oniguruma')) {
      return '\0stub:js-engine';
    }
  },
  load(id) {
    switch (id) {
      case '\0stub:noop':
        return 'export default () => {};';
      case '\0stub:empty-array':
        return 'export default [];';
      case '\0stub:js-engine':
        return 'export { createJavaScriptRegexEngine } from "@shikijs/engine-javascript";';
    }
  }
});

原始 SSR bundle:
├── React/Vue 框架代码     ~300 KiB
├── 业务逻辑代码           ~200 KiB
├── Mermaid 图表库        ~1200 KiB  ❌ 服务端不需要
├── Cytoscape 图论库       ~800 KiB  ❌ 服务端不需要
├── Shiki 语法定义         ~500 KiB  ❌ 服务端不需要
├── WASM 运行时            ~200 KiB  ❌ Workers 不兼容
└── 其他依赖              ~300 KiB

总计: ~3.5 MiB (超过 3 MiB 限制 ❌)

优化后 SSR bundle:
├── React/Vue 框架代码     ~300 KiB
├── 业务逻辑代码           ~200 KiB
├── Mermaid stub            ~0 KiB   ✅
├── Cytoscape stub          ~0 KiB   ✅
├── Shiki 精简版           ~50 KiB   ✅
├── JS 正则引擎            ~50 KiB   ✅
└── 其他依赖              ~300 KiB

总计: ~900 KiB (远低于 3 MiB 限制 ✅)

# 使用 wrangler 分析 bundle 大小
wrangler deploy --dry-run --outdir .wrangler/dist

# 查看各文件大小
ls -lh .wrangler/dist/

// stubs/mermaid.ts
export default {
  render: () => Promise.resolve(''),
  initialize: () => {},
};

// stubs/cytoscape.ts  
export default () => ({
  add: () => {},
  layout: () => ({ run: () => {} }),
});

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    {
      name: 'custom-ssr-stubs',
      enforce: 'pre',
      resolveId(id, importer, { ssr }) {
        if (!ssr) return null;
        
        // 映射到本地 stub 文件
        const stubs: Record<string, string> = {
          'mermaid': '/stubs/mermaid.ts',
          'cytoscape': '/stubs/cytoscape.ts',
        };
        
        if (stubs[id]) {
          return stubs[id];
        }
      }
    }
  ]
});

// 组件代码无需修改
import Mermaid from 'beautiful-mermaid';

function Diagram({ code }) {
  useEffect(() => {
    // 客户端正常执行
    Mermaid.render(code);
  }, []);
  
  // 服务端返回占位符
  return <div className="mermaid-placeholder">{code}</div>;
}

// 代替静态导入
// import HeavyChart from 'heavy-chart-lib';

// 使用动态导入
const HeavyChart = lazy(() => import('heavy-chart-lib'));

function ChartPage() {
  return (
    <Suspense fallback={<ChartSkeleton />}>
      <HeavyChart data={data} />
    </Suspense>
  );
}

// 错误：缺少必要导出
export default {};

// 正确：模拟库的 API 结构
export default {
  render: () => Promise.resolve(''),
  parse: () => ({}),
  initialize: () => {},
};

// stubs/mermaid.d.ts
declare module 'beautiful-mermaid' {
  export function render(code: string): Promise<string>;
  export function initialize(config: any): void;
}

// 服务端 stub
export function renderToString() {
  // 返回与客户端一致的占位结构
  return '<div class="chart-container"></div>';
}