换一种路由体验Convex Better Auth 集成 Hono 框架指南【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-authConvex Better Auth 是一套把 Better Auth 认证能力无缝接入 Convex 后端的官方组件方案它默认使用 Convex 自带的 HttpRouter 来挂载认证路由。如果你更喜欢灵活、轻量的 Hono 框架完全可以用它替换默认路由器体验更自由的路由编排。本文将用最少的代码带你完成 Convex Better Auth 与 Hono 框架的集成配置并解决 CORS、路由重定向等常见问题。什么是 Convex Better Auth简单来说Convex Better Auth 是一个 Convex ComponentConvex 组件它提供了 Better Auth 与 Convex 之间的集成层让你能✅ 用邮箱密码、OAuth、双因素认证2FA等能力快速构建认证系统✅ 把用户、会话数据直接存在 Convex 数据库中✅ 支持 React、Next.js、SvelteKit、TanStack Start、Hono 等主流框架✅ 内置 JWT 签发、Cookie 管理、JWKS 端点与 Convex 的鉴权体系深度打通默认情况下你只需要在convex/http.ts里调用authComponent.registerRoutes()认证路由就会被自动挂载到 Convex 的 HTTP 路由上非常省心。为什么要把默认路由器换成 HonoHono 是近年来非常流行的轻量级 Web 框架主打零依赖、超快、TypeScript 友好。相比 Convex 默认的 HttpRouterHono 的优势在于对比维度Convex 默认 HttpRouter换成 Hono 之后路由表达能力相对基础支持中间件、子路由、复杂匹配生态扩展有限可复用 Hono 全家桶中间件灵活性固定注册方式自由编排请求处理逻辑学习成本低低上手几乎无门槛也就是说当你需要更精细地控制请求流程比如统一加日志、鉴权中间件、自定义路由跳转时Hono 会是一个更趁手的路由层。集成 Hono 前需要准备什么开始之前请确认你的项目满足以下条件✅ 已经建好 Convex 项目npm create convexlatest✅ 已安装convex-dev/better-auth组件并完成基础配置✅ 安装convex-helpers包npm install convex-helpersconvex-helpers提供了HonoWithConvex和HttpRouterWithHono两个关键工具是本次集成的基础记得先装好。最快配置方法三步完成 Hono 路由替换整个替换过程非常简洁核心就是修改convex/http.ts这一个文件。可以参考官方文档 Hono 集成说明 和项目中的 Next.js 示例。第 1 步创建 Hono 实例并接管认证路由在convex/http.ts中把原来的httpRouter()换成 Honoimport { Hono } from hono; import { HonoWithConvex, HttpRouterWithHono } from convex-helpers/server/hono; import { ActionCtx } from ./_generated/server; import { createAuth } from ./auth; const app: HonoWithConvexActionCtx new Hono(); app.on([POST, GET], /api/auth/*, async (c) { const auth createAuth(c.env); return auth.handler(c.req.raw); }); const http new HttpRouterWithHono(app); export default http;就这么简单HttpRouterWithHono会把 Hono 应用桥接到 Convex 的 HTTP 路由器上认证请求全部由 Hono 处理。第 2 步添加 OpenID 配置重定向可选如果你需要使用 OIDC 相关能力可以把 well-known 请求重定向到认证端点app.get(/.well-known/openid-configuration, async (c) { return c.redirect(/api/auth/convex/.well-known/openid-configuration); });这样外部服务发现配置时就能自动找到认证入口体验更顺畅。第 3 步启动验证保存文件后运行npx convex dev然后访问http://localhost:3211/api/auth/get-session之类的认证端点确认路由已经由 Hono 正常接管。别忘了 CORSReact/Vite 纯前端项目的关键配置如果你的项目是 React/Vite SPA纯客户端渲染CORS 配置是必须的否则浏览器会拦截认证请求导致登录失败。在 Hono 里配置 CORS 非常简单只需要引入hono/cors中间件import { cors } from hono/cors; app.use( /api/auth/*, cors({ origin: process.env.SITE_URL, allowHeaders: [Content-Type, Authorization, Better-Auth-Cookie], allowMethods: [GET, POST, OPTIONS], exposeHeaders: [Content-Length, Set-Better-Auth-Cookie], maxAge: 600, credentials: true, }) );几个要点origin填你的前端站点地址如http://localhost:5173credentials: true必须开启认证 Cookie 才能跨域携带allowMethods记得包含OPTIONS处理预检请求配置完成后React/Vite 等 SPA 项目就能顺畅调用登录、注册、会话等全部认证接口了。常见问题与排错技巧问题现象可能原因解决办法请求 404Hono 路由路径与认证 basePath 不一致确认/api/auth/*与 Better Auth 的basePath相同登录后前端拿不到会话CORS 未配置或credentials未开启按上文补全 CORS 中间件配置TypeScript 报错convex-helpers未安装执行npm install convex-helperswell-known 404缺少重定向路由添加 OpenID 配置重定向代码相关文件速查集成过程中涉及的关键文件方便你对照查看Hono 集成官方文档最权威的配置说明Convex 插件源码了解 JWT、Cookie、JWKS 如何工作Next.js 完整示例默认路由挂载的参考实现Convex 组件客户端说明registerRoutes等方法的使用细节总结把 Convex Better Auth 的默认路由换成 Hono只需要改一个文件、加一段 CORS 配置就能解锁更灵活的路由能力。无论是全栈框架还是纯前端 SPA这套方案都能帮你快速构建专业、可扩展的认证体系。现在就动手试试感受一下换一种路由体验的畅快吧【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考