项目结构

理解 Qwik Router 的入口文件、路由目录与请求生命周期。

约 3 分钟Qwik v202 / 19

本页目录5 节

默认目录
入口文件
路由文件的三种角色
一次请求的顺序
服务端专用模块

Qwik 的目录结构把服务器入口、文档外壳和路由分开。大部分业务代码活在 src/routes 与 src/components 里，框架配置只在少数几个文件中出现。

01默认目录#

text项目根目录

src/
  root.tsx            文档的 <head> 与 <body>
  entry.ssr.tsx       服务端渲染入口
  entry.preview.tsx   preview 用的 Node 中间件
  routes/
    layout.tsx        所有页面共享的布局
    index.tsx         首页 /
    docs/
      layout.tsx      文档区布局
      [...slug]/
        index.tsx     动态文档页
  components/
    site/             页头、页脚、主题切换
    docs/             文档排版与代码块
    home/             首页交互演示
  data/
    docs/             文档内容与索引
  styles/             设计令牌与全局样式
public/               静态资源
vite.config.ts        Vite + Qwik 插件配置
tsconfig.json         TypeScript 配置

02入口文件#

文件	职责
`src/root.tsx`	返回 `<head>` 与 `<body>`，挂载 `RouterOutlet`，决定全局 head 内容。
`src/entry.ssr.tsx`	用 `createRenderer` 把根组件交给 Qwik Router，设置语言、容器属性与默认 head。
`src/entry.preview.tsx`	生产预览用的 Node 中间件，只在 `preview` 与部署适配器中使用。
`vite.config.ts`	注册 `qwikRouter()` 与 `qwikVite()` 插件，配置 Vite 优化项。

03路由文件的三种角色#

index.tsx：页面。默认导出 component$，渲染 HTML 响应。
index.ts：端点。导出 onGet、onPost 等 handler，直接返回 JSON、文本或重定向。
layout.tsx：布局。为子路由提供共享 UI，也可以实现 onRequest 等请求拦截逻辑。

textsrc/routes

routes/
  layout.tsx                 所有页面共享
  index.tsx                  /
  about/
    index.tsx                /about
  docs/
    layout.tsx               /docs/*
    [section]/
      index.tsx              /docs/:section
    [...slug]/
      index.tsx              /docs/任意/深层/路径
  api/
    products/
      index.ts               /api/products（JSON 端点）

静态段优先于 [param]，[param] 优先于 [...catchAll]。路由匹配按段从左到右比较，与目录创建顺序无关。

04一次请求的顺序#

01
SSR 入口
entry.ssr.tsx 创建渲染器，接收请求。
02
中间件
plugin@*.ts 与布局的 onRequest 依次运行。
03
数据加载
全局 loader 与当前路由的 routeLoader$ 在组件渲染前完成。
04
渲染
根布局、嵌套布局、页面组件依次输出 HTML。
05
序列化
组件边界、事件与状态写入 HTML，浏览器之后从这里续接。

05服务端专用模块#

以 .server.ts 结尾的文件，以及 src/**/server/** 下的模块，只能在 SSR 代码、loader、action、端点和 server$ 中导入。客户端代码如果误引入，构建会失败：

tsxsrc/db.server.ts

export const findUser = async (id: string) => {
  return db.users.findUnique({ where: { id } });
};