---
url: /docs/frontend/routing.md
---
# 页面路由

## 文件路由

工作台使用 TanStack Router，页面文件在 `apps/app/routes/`。`__root.tsx` 提供根布局，`(auth)` 放登录和找回密码页面，`(app)` 放需要会话的工作台页面；括号目录用于分组，不作为网址的一部分。

`lib/routeTree.gen.ts` 由路由插件生成。新增页面后启动开发服务或构建以更新它，不手动维护生成内容。

## 私有页面与公开页面

`(app)/route.tsx` 的 `beforeLoad` 读取统一会话查询，未登录时跳转登录。公开营销、博客和工具页面放在 `apps/web/pages/`，由 Astro 输出静态正文。

新工作台页面还要在 `apps/web/worker.ts` 和 `scripts/local-gateway.ts` 注册对应顶层路径，否则站内跳转可能正常，直接打开或刷新却落到公开站。验证双向路径归属的测试在 `apps/app/lib/edge-routing.test.ts`。

## 新增页面流程

1. 参考相邻路由创建文件并导出 `Route`，设置加载和错误状态。
2. 需要私有访问时放入 `(app)` 分组，使用统一会话与查询模块。
3. 增加导航入口，并同步边缘路径归属。
4. 构建后分别检查站内点击、直接访问、刷新和退出后访问。

网址查询参数通过路由的校验配置读取，限制长度和可选值。登录回跳地址必须校验为站内路径，不能接受任意外部地址。

详见 [新增页面](../recipes/new-page.md) 和 [会话与访问控制](../auth/sessions.md)。