一个已经上线的项目，所有页面公开，所有接口谁调都信。直到朋友把后台地址丢进群聊，才想起"登录以后再加"这句话已经拖了太久。给运行中的应用补认证，和从零起一个新项目完全是两回事——路由、布局、数据都在那儿摆着，脚手架救不了你，需要的是一组能一口气读完、出错还能回滚的小改动。

这份实践用开源 TypeScript 认证库 theAuth 走了一遍全程：给 Next.js App Router 应用加上用户名密码登录、Cookie 会话和受保护页面。作者说，全部改动大约 150 行代码，涉及六七个文件，手动新增的数据库表为零。

打开网易新闻 查看精彩图片

先看清它的取舍

theAuth 的设计是"智能体优先"。它内置的人类登录方式是用户名加密码，不是邮箱加密码；而且是无头的——没有预置登录页，社交登录按钮也不默认接好。如果你想要十分钟内跑通邮箱登录加托管界面，Clerk 或 Auth.js 会更快。如果你想要一个以后还能给 AI 智能体发身份的库，再往下看。

环境要求不复杂：已有的 Next.js App Router 应用，适配器声明的对等依赖是 next >= 14；Node.js 18 或更高；一个数据库，本地开发用 SQLite 免配置，生产环境考虑 Postgres、MySQL 或 Cloudflare D1。theAuth 会用自己的 theauth_ 前缀建表，不碰你现有的表结构。

装包与密钥

核心安装只有一条命令，一个包就带上了核心、SQLite 驱动（sql.js，编译成 WebAssembly）、用户名模块和会话管理器。用 Postgres 的话，额外装上 pg 驱动。数据库驱动是可选的对等依赖，只有选中对应提供方时才会加载，忘了装会得到一个明确报出缺失包名的启动错误。

会话密钥用 openssl 生成一串 base64 随机值，写进 .env.local。这个密钥给每个会话令牌签名，theAuth 会拒绝长度不足 32 个字符的值。它必须在多次部署之间保持稳定——换新密钥会让所有已发出的 Cookie 失效，等于把全部用户一次性登出。官方文档也写明不支持密钥列表轮换，要改就挑个安静的时间段。

两个文件搭起骨架

第一个文件很短，只放 Cookie 名称和应用来源地址，这样中间件之后可以引用它们，而不必连带拉进数据库驱动。第二个文件构建 theAuth 实例和 Cookie 会话管理器，每个进程只建一次。

初始化时按环境切换数据库：生产用 Postgres 加 DATABASE_URL，开发用 SQLite 指向本地文件。会话配置里指定密钥、Cookie 名、有效期 7 天，并关掉自动刷新。Cookie 选项设成 httpOnly、生产环境 secure、sameSite 为 lax、路径为根。

代码里还有一道自检：如果用户名模块没起来，直接抛错提示检查 auth.session 配置，避免带着半残状态往下跑。

整套改动没有引入新表，没有重写路由，也没有把现有页面推倒重来。它更像是在一栋住着人的房子里换锁——动静要小，步骤要能倒着走，出问题时你知道该退回哪一步。