Better Auth 环境变量完全指南：3 分钟跑通配置 + 敏感密钥全防护

Better Auth 环境变量完全指南3 分钟跑通配置 敏感密钥全防护【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-authBetter Auth 环境变量配错一个本地好好的登录流程上线后可能直接全线停摆社交登录回调打不开、会话突然全部失效、密钥跟着代码一起被推上仓库。别慌这类问题九成出在配置层而不是代码层。这篇指南带你从「最小可运行配置」开始把变量加载规则、社交登录变量、密钥轮换到高频报错一次讲透让你 3 分钟跑通 Better Auth 环境变量配置再顺手把敏感信息防护补齐。最小可运行配置两个变量 3 分钟跑通 Better Auth想让 Better Auth 转起来其实只需要在项目根目录建一个.env文件写进两个变量缺一不可BETTER_AUTH_SECRET加密会话、签发令牌用的核心密钥要求至少 32 个字符且具备高随机性BETTER_AUTH_URL你的应用基础地址回调 URL 和 Cookie 的 domain 都靠它拼生成密钥别手写一行命令搞定高熵随机值# 方案 A系统 openssl openssl rand -base64 32 # 方案 BBetter Auth CLI 直接生成可粘贴的变量行 npx better-auth/cli secret拿到值后填进.envBETTER_AUTH_SECRET把上面生成的值粘贴到这里 BETTER_AUTH_URLhttp://localhost:3000⚠️BETTER_AUTH_URL开发环境写localhost:端口上线前务必改成正式域名否则 OAuth 回调和 Cookie 作用域都会出问题。密钥以后想换不用推倒重来——Better Auth 支持在.env里配置复数形式的BETTER_AUTH_SECRETS新旧密钥并存做灰度过渡存量会话不会被直接作废细节见官方安装文档里的secrets说明。环境变量加载优先级.env 到底按什么顺序生效很多「明明写了变量却不生效」的困惑根源在于没搞清楚加载顺序。Better Auth 本身不重复造轮子它依赖你所用框架的标准 dotenv 机制按以下优先级从高到低取值系统环境变量如 CI/CD 注入、云平台的 Secret 配置——最高优先级.env.local——本地覆盖层适合写你机器上的个人配置.env——基础默认值进仓库的是它放空值模板即可这套机制带来一个实用结论.env里放「有默认值、不敏感」的项.env.local放「因人而异」的项真正敏感的密钥通过 CI/CD 平台注入。同一变量三处都写了时系统环境变量会直接盖掉文件里的值。不同框架下变量都是经由process.env或框架等价物被读进auth.ts。以 Next.js 为例路由侧只需一行桥接import { toNextJsHandler } from better-auth/next-js; import { auth } from /lib/auth; export const { POST, GET } toNextJsHandler(auth);Nuxt、SvelteKit、Express 等框架的接入方式在官方安装文档中都有对应章节套路一致建实例 → 接数据库 → 挂路由变量读取方式不变。社交登录环境变量GitHub / Google 接入要补哪些配置基础配置跑通后想开社交登录规则很简单每个 Provider 一对变量命名遵循「大写服务名 CLIENT_ID/CLIENT_SECRET」然后在socialProviders里引用即可。以 GitHub 为例import { betterAuth } from better-auth; export const auth betterAuth({ socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, }, });GITHUB_CLIENT_ID你的-GitHub-App-Client-ID GITHUB_CLIENT_SECRET你的-GitHub-App-Client-SecretGoogle、Apple、Discord、Microsoft 等主流 Provider 都是同一套模式。到底要补哪些变量可以直接对照仓库里的官方示例清单 demo/nextjs/.env.example——所有支持的 Provider 变量名都列在那一份文件里照着抄不会错。 铁律CLIENT_SECRET这类值永远只走环境变量代码里出现clientSecret: 写死的值就是事故隐患。给 BETTER_AUTH_SECRET 上锁生产环境密钥防护与轮换清单密钥是整条认证链的信任根防护可以浓缩成一张清单逐项打勾即可别进版本库仓库的 .gitignore 已默认忽略.env、.env.local、.env.production.local等文件确认你的项目同样处理仓库里只保留空值的.env.example模板环境隔离不同环境用不同文件.env.development/.env.production生产密钥只存在于 CI/CD 的密钥管理或云平台 Secret 服务如 AWS Secrets Manager中文件权限收紧服务器上的.env建议设为仅所有者可读写权限600减少横向读取风险定期轮换把「轮换BETTER_AUTH_SECRET」写进运维日历。轮换时用复数形式的BETTER_AUTH_SECRETS让新旧密钥并行过渡避免存量用户会话被一刀切断需要新密钥时npx better-auth/cli secret随时可生成实现见 packages/cli/src/commands/secret.ts安全细节与响应流程可继续参考 SECURITY.md它是这套框架对外承诺的安全基线。踩坑急救箱变量没生效三步定位高频报错遇到报错先别怀疑框架按「查名字 → 查加载 → 查环境」三步走绝大多数问题三分钟定位症状大概率原因处理动作启动报「secret 长度不足 / 缺失」BETTER_AUTH_SECRET为空或少于 32 字符用openssl rand -base64 32重新生成并替换改了.env却不生效变量名拼错如SECRECT、或框架没重启逐字符核对变量名重启 dev server 后再试多环境值「串台」系统变量 /.env.local覆盖了.env按「系统 .env.local.env」的顺序确认谁在生效社交登录回调报invalid_codeBETTER_AUTH_URL与 OAuth 平台登记的回调地址不一致两边地址对齐生产环境必须 HTTPS最后一行是最典型的「配置型故障」BETTER_AUTH_URL写的是localhost而线上域名不同回调就对不上最终落在这个错误页。另外建议给变量读取加一层「启动即校验」关键变量取不到就直接抛错拒绝启动把配置问题挡在部署阶段而不是等用户触发时才暴露。延伸阅读文档与源码速查安装与环境变量官方文档两个核心变量、BETTER_AUTH_SECRETS轮换的权威出处demo/nextjs/.env.example所有社交登录 Provider 变量名的现成清单SECURITY.md安全承诺、漏洞披露与防护基线packages/cli/src/commands/secret.tsCLI 一键生成密钥的实现demo/nextjs/lib/auth.tssocialProviders完整配置的真实示例把「两个核心变量 一套加载规则 一张防护清单」记牢Better Auth 的环境变量配置就再也不会成为你上线路上的暗礁了。【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考