上一篇还在写后台登录验证码,这一篇画风突变:折腾了几天,把博客前端换成了 Next.js。

先给结论:后端还是 FastAPI,数据库还是 MySQL,Jinja2 后台也没有一口气全扔。这次只是把公开页面和一部分后台搬到了 Next.js,属于“慢慢拆”,不是“推倒重来”。

为什么要换

原来那套 FastAPI + Jinja2 其实挺省心:一个进程、一套模板,页面由服务端直接吐出来。写内容站完全够用。

但看久了还是想折腾。模板做复杂交互会比较别扭,样式一多,HTML 和 CSS 也开始互相打架。再加上我本来就想让前端看起来更像一个“正经博客”,而不是后台模板换了层皮,所以决定把 Next.js 引进来。

目标有两个:

  • 页面要更好看,交互更顺;
  • 后端业务逻辑尽量不动,别为了换前端把数据库、认证和后台全重写。

方案:后端不动,前端重做

最后选的是“保留 FastAPI 后端 + 新建 Next.js 前端”:

  • Next.js 16 App Router、React 19、TypeScript、Tailwind CSS 4;
  • FastAPI 继续负责数据库、认证、Markdown 渲染、上传、限流;
  • 前端通过 /api/v1 读数据,登录和写入继续用同源 Session + CSRF;
  • 生产环境用 Nginx 做同源反向代理,浏览器只看到一个域名。

没有把 FastAPI 换成 Next.js 的 API Routes。理由很简单:后端已经能跑,业务逻辑和测试都在,没必要为了“技术统一”重写一遍。

公开页面先搬

第一批迁的是公开页面:首页、文章列表、文章详情、标签、归档、搜索、动态、留言、关于。

视觉上换成了深蓝紫渐变、玻璃卡片和一点点流体感。首页加了 hero 和统计卡片,文章页保留窄正文栏和目录。移动端也重新做了一版,至少不再是“桌面端缩窄一点”。

渲染方式还是服务端渲染,暂时没上 ISR。内容更新不频繁,但我不想为了缓存再引入一套失效逻辑,先让数据实时一点。

这次最费时间的不是页面,而是登录。

Next.js 服务端渲染时要把浏览器的 Cookie 转给 FastAPI。最开始我用 cookies().toString() 重新拼 Cookie,看起来没问题,结果登录后页面永远显示未登录。

查了半天才发现:Starlette 的 Session Cookie 是签名过的,重新序列化会改变字符串,后端验签直接失败。

后来改成直接读原始请求头:

const cookieHeader = (await headers()).get("cookie") ?? "";

再把这段原始字符串转给 FastAPI,登录状态才正常。

还有一个相关问题:登录和退出之后不能只做客户端路由跳转,否则 Next.js 的客户端缓存里还挂着旧布局。现在登录成功、退出成功都直接整页跳转,简单粗暴,但不会出现“后端已经登录、页面还显示登录按钮”的尴尬。

后台没有一次迁完

后台登录、邮箱验证码、TOTP 我还是留在 FastAPI。它们和 Session、CSRF、限流绑得太紧,先不动。

Next.js 先接管了 /admin 仪表盘和 /admin/posts 文章列表;文章编辑、评论审核、用户管理这些还在旧 Jinja 后台。

这里也有路由问题:/admin、/admin/posts 要让 Next.js 优先,其他 /admin/* 继续给 FastAPI。最后在 next.config.ts 里把 rewrites 放到 afterFiles,生产 Nginx 再按路径分流。

一个很隐蔽的路由冲突

迁移后台 API 时踩了一个很阴的坑。

FastAPI 里原来有一个 HTML 文章详情路由,名字叫 post_detail。我加后台 API 时又写了一个同名的 post_detail。结果模板里的 url_for("post_detail", ...) 不声不响地选中了后台 API 路由。

于是访问 /posts/1 会被 301 到 /api/v1/admin/posts/1,然后因为没登录直接 401。前台文章页看起来就像“突然坏了”。

这个问题不是靠看页面能发现的,是回归测试里 /posts/1 返回 401 才暴露出来。修复方式很朴素:给每个路由起唯一的名字,再补一个测试,专门检查旧文章 ID 跳转不会跑到 /api/ 下面。

测试怎么做的

前端用 Playwright 跑了两层:

  • mock API:覆盖公开页面、登录、评论、留言、后台 UI;
  • 真实 FastAPI + 一次性 SQLite:覆盖真实 Session、CSRF 和写库。

后台又单独验了一遍真实流程:管理员登录 → /admin 仪表盘 → /admin/posts → 旧文章编辑页。

上线前还本地搭了一套 HTTPS 模拟:Nginx + 自签名证书 + 生产构建 + SESSION_HTTPS_ONLY=true,确认 __Host-blog_session、后台登录和评论写入都能走通。

代价

这次重构不是没有成本:

  • 开发时前后端要同时启动;
  • 生产多了 Next.js 进程和 Nginx 分流;
  • NEXT_PUBLIC_SITE_URL 是构建时变量,改域名必须重新 build;
  • 后台现在一半 Next、一半 Jinja,看起来不太统一。

但换来的东西也很直接:前端终于可以按组件和设计系统来写,页面不再被模板语法限制;后端还是原来那套,数据库和业务逻辑没被折腾。

最后

这次没有追求“一步到位”。公开页面先迁,后台只迁最常用的仪表盘和文章列表,剩下的慢慢来。

现在上线前还在收尾:Nginx、HTTPS、备份和真实邮件都还要在服务器上验一遍。等后台也迁完,再写一篇“全 Next.js 后台”的。

至少目前看,这次折腾是值得的。