博客系统从 React+Vite 迁移到 Next.js 16 踩坑记录

2026-05-03，把个人博客前端从 React+Vite 迁移到 Next.js 16，部署到 Vercel，后端留在腾讯云 Docker。中间踩了不少坑，记录一下。

坑 1：npm 不支持 pnpm workspace 协议#

现象：在 Windows 上 npm install 报错 TypeError: Invalid Version: 。

原因：package.json 里用了 "@workspace/api-client-react": "*"，这是 pnpm 的 workspace 写法。Windows 上的 npm 解析这个包名时遇到空版本号，直接崩了。

解决：把 api-client-react 的代码直接内联到 src/lib/api-client-react/ 下，去掉 cross-workspace 依赖，所有 import 改成 @/lib/api-client-react。

现象：已经把 import 路径从相对路径改成 @/ 别名，但构建还是报 Module not found: Can't resolve '../../lib/api-client-react'。

原因：Next.js 16 默认用 Turbopack，它有缓存。改了文件但缓存没失效，还在用旧内容。

解决：手动删 .next 目录再重新构建。rm -rf .next && npm run build。

现象：用脚本批量替换 import 路径，检查发现只有 1 个文件替换成功，其他 9 个还是旧路径。

原因：第一次写的正则 /[^"]*lib\/api-client-react"/ 匹配范围太窄，带 @workspace/ 前缀的路径没匹配到。

解决：换成更宽泛的正则 r'"[^"]*lib/api-client-react"'，匹配所有包含 lib/api-client-react 的 import 字符串。

教训：批量替换后一定要 grep 验证，别假设全部成功。

现象：访问 /admin/login 页面空白，啥都没有。

原因：app/admin/login/page.tsx 放在 app/admin/ 目录下，被 admin/layout.tsx 包裹。layout 里有权限检查逻辑——未登录时 router.push("/admin/login")。结果：

解决：把登录页移到 app/admin-login/page.tsx，脱离 admin layout，独立成一个页面。layout 里的跳转路径也相应改成 /admin-login。

现象：后端登录返回 200，但没有 Set-Cookie header，前端无法保持登录态。

原因：后端是 HTTP（secure: false），但 Vercel 前端是 HTTPS。浏览器要求 SameSite=None 必须带 Secure 标志，而后端设的是 secure: false，浏览器直接丢弃这个 cookie。

解决：后端保持 secure: false（因为后端本身是 HTTP），在 Next.js API Route 代理层做 cookie 重写——把 Set-Cookie 里的 SameSite=None 替换成 SameSite=None; Secure，补上 Secure 标记。

现象：用 api.ipify.org 查出来的 IP 配到 Vercel 环境变量后代理连不上。

原因：服务器装了 tailscale（或其他 VPN），出口流量走了 VPN 节点，api.ipify.org 返回的是 VPN 出口 IP，不是服务器的真实公网 IP。

解决：通过 httpbin.org/ip 直连确认真实公网 IP，或者直接看服务器网卡信息。

现象：Vercel 自动拉取部署时出问题，commit 显示的 author 和 GitHub 账号对不上。

原因：本地 git config 用的邮箱和 GitHub 账号绑定的邮箱不一致。

解决：在项目目录下单独设置 git 邮箱（不影响全局）：

1
git config user.email "你的GitHub邮箱"
2
git config user.name "你的GitHub用户名"