踩坑记录：从 bcrypt 版本到 Hydration 不匹配

开发踩坑记录

在博客开发过程中遇到了 7 个典型问题，从后端到前端覆盖整个技术栈。

问题：安装依赖后启动后端，登录时报错 password cannot be longer than 72 bytes。

根因：passlib 1.7.4 使用了 bcrypt 的内部 API，bcrypt 5.x 移除了这个 API。

解决：将 bcrypt 降级到 4.0.1：

pip install bcrypt==4.0.1

问题：在 Ubuntu 服务器上运行 npm run build 报错，提示 styleText API 未定义。

根因：Nuxt 3.13+ 使用了 Node.js 20 新增的 styleText API，但 Ubuntu apt 源上的 Node.js 版本是 18.x。

解决：从 nodesource 安装 Node.js 20：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs
node -v  # 确认 v20+

问题：Comment 模型自引用关系（parent_id 指向同一张表）加上 cascade="all, delete-orphan" 后启动报错。

根因：SQLAlchemy 不支持自引用关系的 delete-orphan 级联。

解决：删除 cascade 参数，改为 ondelete="SET NULL"：

parent_id = Column(Integer, ForeignKey("comments.id", ondelete="SET NULL"), nullable=True)

这样父评论删除时子评论的 parent_id 置为 NULL（变成顶级评论），而非被级联删除。

问题：from . import models 在 uvicorn main:app 模式下报 ImportError。

根因：uvicorn 直接运行 main.py 时，模块的 __package__ 属性为空，相对导入无法工作。

解决：全部改用绝对导入：

# ❌ from . import models
# ✅ import models
from database import get_db
from models import Article

问题：浏览器控制台报 Hydration children mismatch。

根因：Vue 3 要求 SSR 输出和客户端首次渲染的 DOM 完全一致。以下情况会导致不匹配：

解决：

问题：SQLite 数据库 URL 在 Windows 下路径格式不正确。

根因：SQLAlchemy 的 SQLite URL 需要 POSIX 风格的正斜杠路径，但 Path 对象在 Windows 上输出反斜杠。

解决：使用 .as_posix() 统一转正斜杠：

DATABASE_URL = f"sqlite:///{(DATA_DIR / 'blog.db').as_posix()}"

在 Linux 上 .as_posix() 不改变路径（本来就是正斜杠），Windows 上 \ 转为 /。

问题：服务器上 npm run build 报错，提示模块不兼容。

根因：本地 Windows 上 npm install 产生了平台特定的 native binding（node-sass、esbuild 等），而服务器是 Linux。

解决：服务器上先清除再重新安装：

rm -rf node_modules package-lock.json
npm install

服务器安装时会自动下载 Linux 平台的 binding。

这些踩坑记录反映出几个通用规律：