理解 Qwik 的 routeLoader$：执行时机与 SSR/SSG/CSR 全景解析

#🔑 一句话定义

复制import { routeLoader$ } from '@builder.io/qwik-city';

routeLoader$ 是 Qwik City 专为“路由级数据加载”设计的声明式 API。
它将数据获取逻辑与组件解耦，通过 序列化 + 状态恢复 实现“零 hydration”体验——这正是 Qwik “可恢复性”（Resumability）架构的灵魂所在。

#📊 执行时机全景表（建议收藏！）

💡 术语澄清：Qwik 中“CSR”通常指 客户端路由导航行为，而非整个应用无服务端渲染。Qwik 应用本质是 混合渲染架构。

#🔍 深度剖析：三个场景的“灵魂拷问”

#🌤️ SSR：服务端的“一次性交付”

复制// routes/product/[id]/page.tsx
export const useProduct = routeLoader$(async (event) => {
  // event 仅服务端存在！可安全读取 cookies/headers
  const token = event.cookie.get('auth');
  return await db.getProduct(event.params.id, token);
});

• ✅ 优势：首屏数据完整、SEO 友好、用户秒开
• ⚠️ 注意：客户端恢复时绝不重执行，数据已序列化到 <script type="qwik/state"> 中

#📦 SSG：静态生成的“双面人生”

复制# 构建时执行（生成 product-123.html）
npm run build

• 直接访问（用户输入 URL）：
  → 用构建时序列化的数据，零请求，极致速度 ✅
• 客户端导航（从首页点击链接跳转）：
  → Qwik Router 动态加载路由代码 → 在浏览器重新执行 routeLoader$ ⚠️
  → 若 API 返回空（如需登录），页面显示异常！

🌰 我的血泪教训：
产品页用 SSG 生成，但价格需实时查询。
解决方案：

复制// loader 中同时返回构建时快照 + 标记
return { 
  snapshot: buildTimeData, 
  needsRefresh: true // 客户端导航时触发刷新逻辑
};

配合 useVisibleTask$ 在客户端条件更新，平衡速度与实时性。

#🔄 客户端导航：SPA 式体验的“幕后引擎”

• 无论初始页是 SSR/SSG，新路由的 loader 总在客户端执行
• Qwik 内置缓存：相同路由参数（如 /user/1）多次访问不重复请求
• 与 routeAction$ 严格分工：
  • loader = 读数据（GET 语义，可缓存）
  • action = 写操作（POST 语义，防重复提交）

#🛠️ 实战代码：安全处理环境差异

复制export const useUserProfile = routeLoader$(async (event) => {
  // 🔒 安全访问服务端上下文
  const userId = event?.sharedMap.get('userId'); // 仅服务端存在
  
  // 🌐 客户端导航时的降级方案
  if (!userId && typeof window !== 'undefined') {
    const stored = localStorage.getItem('temp_user_id');
    if (stored) return { id: stored, name: 'Guest' };
  }

  // 📡 统一数据获取逻辑（服务端/客户端均可运行）
  const res = await fetch(
    userId 
      ? `/api/user/${userId}` 
      : '/api/user/guest'
  );
  return res.json();
});

// 组件中直接使用
export default component$(() => {
  const user = useUserProfile();
  return <div>Welcome, {user.value.name}!</div>;
});

✅ 最佳实践：

1. 将依赖 event 的逻辑做条件判断
2. 客户端需兼容 event 为 undefined 的情况
3. 敏感操作（如权限校验）放在服务端 loader，客户端仅做展示

#💡 核心思想总结