上一篇还在写后台登录验证码,这一篇画风突变:折腾了几天,把博客前端换成了 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。内容更新不频繁,但我不想为了缓存再引入一套失效逻辑,先让数据实时一点。
Cookie 的坑
这次最费时间的不是页面,而是登录。
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 后台”的。
至少目前看,这次折腾是值得的。
评论
登录后评论
暂无评论。