Better Auth 环境变量完全指南：2 个必配项、密钥轮换与避坑速查

Better Auth 环境变量完全指南2 个必配项、密钥轮换与避坑速查【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-authBetter Auth 是目前覆盖面最广的开源认证框架邮箱密码、社交登录、Passkey、SSO 一应俱全。它的稳定运行第一道门槛就是 Better Auth 环境变量BETTER_AUTH_SECRET配错或放错位置轻则登录直接报错重则密钥随代码仓库泄露。这篇文章按「最小配置 → 按需扩展 → 框架接入 → 生产加固 → 排错」的顺序带你把它配好、配安全。一、先看风险变量配错到底会出什么事 两类最高频的事故事故典型表现根因认证失效登录后立刻被登出、OAuth 回调报 400BETTER_AUTH_URL与实际域名不一致回调地址对不上密钥泄露会话令牌可被伪造BETTER_AUTH_SECRET硬编码进代码进了仓库或误用默认值为什么框架把环境变量看得这么重会话令牌session token是用户登录成功后、服务端发给他用来证明我是我的凭证。Better Auth 用BETTER_AUTH_SECRET对它做签名和加密——密钥丢了等于谁都能伪造身份。所以框架在生产环境检测到默认密钥时会直接抛错拒绝启动而不是先跑起来再说。配置正确后的运行效果二、最小可用配置两个变量跑起来 第一步生成 BETTER_AUTH_SECRET必选这是加密会话和签发令牌的根密钥要求至少 32 字符、高熵随机值。别自己编直接用命令生成# 二选一 openssl rand -base64 32 npx auth secret把输出粘贴进项目根目录的.envBETTER_AUTH_SECRETa3F9cD7kQ2mX8vN5rT1wL4yB6sE0uJ9h⚠️ 注意这个值一旦用于线上数据库就不能随便换——换法见第五章的密钥轮换。第二步设置 BETTER_AUTH_URL必选应用的基础域名框架用它拼 OAuth 回调地址、决定 Cookie 写到哪个域。不设的话它会退化成从当前请求推导回调和跳转很容易出 bugBETTER_AUTH_URLhttp://localhost:3000 # 开发环境 # BETTER_AUTH_URLhttps://auth.yourdomain.com # 生产环境第三步实例化 auth 并接上数据库import { betterAuth } from better-auth; import { drizzleAdapter } from better-auth/adapters/drizzle; import { db } from /db; // 你的 drizzle 实例 export const auth betterAuth({ database: drizzleAdapter(db, { provider: pg }), });到这里Better Auth 环境变量最小集就齐了两个变量 一个数据库连接登录链路即可跑通。三、想加社交登录按 Provider 补变量以 GitHub 为例每个第三方登录方都要一对clientId/clientSecret全部走环境变量注入socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, }GITHUB_CLIENT_IDIv1.9f2b3c4d5e6a7012 GITHUB_CLIENT_SECRETghc_a81f3e2b9c4d7f06e2a1b5c9d3f7a0e8命名规律与一个容易踩的坑规律是PROVIDER_CLIENT_ID/PROVIDER_CLIENT_SECRET加多少登录方就补多少对。⚠️ 参考官方 demo 的命名Google 的 ID 用了NEXT_PUBLIC_GOOGLE_CLIENT_ID客户端也要用它发起跳转而 Secret 保持GOOGLE_CLIENT_SECRET。凡是带NEXT_PUBLIC_前缀的变量会被打进前端包Secret 类变量绝不能加这个前缀。四、不同框架里变量是怎么被读到的Better Auth 本身只认 process.env框架自己不解析.env文件它只从process.env取值。.env谁来读、按什么顺序读由你的应用框架决定Next.js、Nuxt、SvelteKit、Express dotenv 等各有各的加载器。完整优先级从高到低运行时注入的环境变量系统 / CI/CD 密钥管理注入最高.env.local本地覆盖不进版本库.env基础配置配置项兜底betterAuth({ secret: ... })里显式传入的值优先于同名环境变量另外框架对密钥做了别名兼容读不到BETTER_AUTH_SECRET时会回退查AUTH_SECRET方便从其他认证库迁移两者都查不到才落到默认值——而默认值在生产环境会直接报错终止。各框架挂载路由的位置路由挂载代码本身不读变量但它依赖上面配好的BETTER_AUTH_URL生成正确的回调。以 Next.js 为例import { auth } from /lib/auth; import { toNextJsHandler } from better-auth/next-js; export const { POST, GET } toNextJsHandler(auth);Nuxt、SvelteKit、Express 的挂法差异只在前几行 import见 安装文档 的 Tabs 示例。五、上线前的加固边配边防 .env 绝不进 Git仓库默认已把它写进.gitignore你的项目请保留这条同时放一份空模板给团队对齐变量名BETTER_AUTH_SECRET BETTER_AUTH_URL GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET密钥轮换方法BETTER_AUTH_SECRETS版本化要轮换BETTER_AUTH_SECRET直接换新值会让存量加密数据全部失效。正确做法是用复数形式的BETTER_AUTH_SECRETS做无损轮换BETTER_AUTH_SECRETS2:bN7pQ2xW9vM4kL1tR6yH0sA3eD5fJ8gC,1:a3F9cD7kQ2mX8vN5rT1wL4yB6sE0uJ9h第一个条目2:...是当前密钥负责所有新加密后面的条目1:...只用于解密密旧数据迁移完成后可摘除旧会话、旧令牌在过渡期照常有效用户无感知。生产环境额外三件事敏感值交给 CI/CD 的密钥管理如各云的 Secrets Manager运行时注入不落盘本地.env文件权限收紧为600仅所有者可读写不同环境用不同密钥值禁止开发、预发、生产共用同一把钥匙。六、排错速查表你看到的现象 / 报错原因解法BETTER_AUTH_SECRET is missing变量没设置或拼错检查.env与变量名拼写重启开发服务器生产启动报You are using the default secret生产环境用了默认密钥设置真实的BETTER_AUTH_SECRETshould be at least 32 characters/low-entropy警告密钥太短或太规律用openssl rand -base64 32重新生成Base URL is not set警告、OAuth 回调 400未设BETTER_AUTH_URL或与实际域名不符设为对外真实域名并确保与第三方平台登记的回调一致改了.env但行为没变框架缓存了旧进程环境变量重启开发服务器确认变量名区分大小写BETTER_AUTH_SECRECT这种拼错不报错、直接无效登录成功但回调后立刻掉登录会话 Cookie 域与 URL 不匹配核对BETTER_AUTH_URL的 schemehttp/https和端口类型层面给process.env加一层校验也能在启动时暴露缺失变量export const getEnv (key: string): string { const value process.env[key]; if (!value) throw new Error(Missing env var: ${key}); return value; };七、收尾一句话总结Better Auth 环境变量 一把根密钥BETTER_AUTH_SECRET 一个基础域名BETTER_AUTH_URL 按需的第三方凭据记住服务端变量不进前端包、.env 不进 Git、轮换走BETTER_AUTH_SECRETS三条纪律认证系统的安全底线就立住了。深入资料均为仓库内相对路径安装与配置全流程secret/secrets选项参考官方 demo 的 .env 变量清单安全声明【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考