常见坑

每一页的标题是报错原文或现象，正文先给最小复现和实际输出，再讲它在源码里怎么产生、怎么改。依赖统一是 topcoat =0.10.0（full）、tokio =1.54.1。

1. 403 forbidden：跨站的 POST 被拦下：子域名表单（same-site 也被拒）、OAuth / OIDC 的 form_post 回调；trust_origins 与 exempt_paths 各自只开一个口子的实测。
2. module path must be under module router's root：根模块之外的 #[page] 让启动 panic；反方向，漏了 mod 的文件静默 404，用 href! 把它变成编译错误。
3. no asset bundle at ...：直接 cargo run 起不来：资产包由 bundler 生成、只在可执行文件旁边找；部署时只拷二进制是同一个错。
4. cannot add a cookie after the response headers have been sent：suspense 里写 cookie 或 session::start，客户端拿到被截断的 200。
5. Failed to compile event @click：$(...) 里的 return、break 与 while：三条已登记的不一致，外加一条没登记的：块末尾的 while 被生成为 return while。
6. 页面要登录，shard 却谁都能请求：上游文档写明的设计，curl 复现越权，两种修法实测。

flowchart TB
  entry["请求入口"] --> p1["403 forbidden"]
  start["启动"] --> p2["module path panic"]
  start --> p3["no asset bundle"]
  stream["流式响应体"] --> p4["cookie 写入 panic"]
  browser["浏览器运行时"] --> p5["Failed to compile event"]
  endpoint["shard、procedure 端点"] --> p6["绕过页面守卫"]