尧图网站建设 
Better Auth 环境变量避坑指南2 个核心变量 密钥轮换一次配好【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-authBetter Auth 是最全面的认证框架Authentication Framework支持邮箱密码、社交登录、Passkey、SSO 等完整能力。而这一切的起点是项目根目录一个不起眼的.env文件——BETTER_AUTH_SECRET和BETTER_AUTH_URL配错或漏配轻则登录回调 404重则生产密钥泄露。本文按本地跑通 → 接入第三方 → 进阶配置 → 排障的真实工作流把 Better Auth 环境变量该知道的都讲清楚。最小可用配置两个变量就能跑起来BETTER_AUTH_SECRET会话加密的根钥匙这个密钥用于会话加密、令牌签名和哈希是整个认证体系信任链的起点。框架的查找逻辑很直白先读BETTER_AUTH_SECRET找不到会退回兼容变量AUTH_SECRET开发环境下两者都缺省会用一个内置默认值兜底但生产环境未设置会直接抛错拒绝启动——这是框架故意做的防线别绕过它。对密钥的要求只有一条至少 32 个字符、高熵随机。别用密码管理器里手敲的看起来很长的口令用工具生成# 方式一openssl 一行搞定 openssl rand -base64 32 # 方式二Better Auth CLI 的 secret 子命令内部是 32 字节随机数 npx authlatest secretCLI 会直接打印出一行可以粘贴进.env的完整内容。实现细节可以看 secret 命令源码环境变量读取逻辑在 env-impl.ts。BETTER_AUTH_URL回调地址和 Cookie 的基准OAuth 回调 URL、邮件里的链接、Cookie 的作用域全部基于这个 URL 拼接。本地开发指向本机地址即可# 根密钥32 位以上高熵随机字符串 BETTER_AUTH_SECRETyour-32-char-high-entropy-secret # 应用基础 URL BETTER_AUTH_URLhttp://localhost:3000如果没显式设置baseURL框架会按BETTER_AUTH_URL、NEXT_PUBLIC_BETTER_AUTH_URL等顺序去环境变量里找。Next.js 项目两个名字都能生效但建议统一用BETTER_AUTH_URL避免团队里混用两套。配好后实例化认证服务放在auth.ts或lib/auth.ts等位置导出变量名为authimport { betterAuth } from better-auth; export const auth betterAuth({ // secret 和 baseURL 已自动从环境变量读取这里只需补数据库等配置 database: { /* 数据库配置 */ }, });接入社交登录第三方凭据怎么放开启 GitHub 登录只需要一对凭据在socialProviders里引用环境变量即可export const auth betterAuth({ socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, }, });GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret凭据放置有三条纪律都是生产事故高发区服务端变量绝不进浏览器在 Next.js 里只有NEXT_PUBLIC_前缀的变量才会被打包进客户端。clientSecret这类值绝不能加该前缀否则等于把钥匙贴在了公网。clientId 可以放宽clientSecret 不行参考官方 demo 的做法NEXT_PUBLIC_GOOGLE_CLIENT_ID给客户端用GOOGLE_CLIENT_SECRET只留在服务端模板见 demo/nextjs/.env.example。禁止硬编码clientSecret: abc123写死在代码里一旦仓库公开或交接就全泄露敏感值一律走环境变量生产环境再叠加 CI/CD 的密钥管理注入。进阶配置密钥轮换与多环境分层用版本化 secrets 做无损轮换密钥泄露或定期换钥是迟早的事而直接替换BETTER_AUTH_SECRET会让存量加密数据全部无法解密。Better Auth 提供了BETTER_AUTH_SECRETS复数解决这个问题按版本组织多个密钥第一项是新写入用的当前密钥其余仅作解密旧数据# 格式版本号:密钥,版本号:密钥第一个为当前加密密钥 BETTER_AUTH_SECRETS2:新密钥base64,1:旧密钥base64轮换时把新密钥作为第一项写入存量会话用旧版本密钥继续解密过渡期结束后再移除最旧的版本。这是改密钥不停服的关键机制配置项说明见 secrets 选项。按环境分层管理配置文件别用一个.env打天下按环境隔离.env团队共享的基础配置非敏感值.env.local本机覆盖优先级高于.env个人数据库地址放这里.env.example提交到仓库的变量清单模板只有 key 没有 value新人照着填优先级从高到低系统环境变量 →.env.local→.env。CI/CD 平台注入的密钥属于系统环境变量天然能覆盖仓库里的文件。另一个容易忽略的进阶项如果应用挂在反向代理后面且没有显式配置baseURL需要谨慎使用trustedProxyHeaders从请求头推断域名——官方文档明确提示配置不当会引入安全漏洞能用静态baseURL或allowedHosts白名单就优先用后者。安全加固别让密钥流向版本库密钥生成得再好管不住出口等于白搭。上线前对照这份清单过一遍版本控制排除.env/.env.local必须在.gitignore中仓库里只保留.env.example模板。已经不小心提交过密钥的正确姿势是先换密钥、再清理历史光删文件没用。文件权限收紧生产服务器的.env建议chmod 600仅所有者可读写防止同机其他账号读取。密钥托管上规模后把核心密钥放进云厂商的 Secrets Manager 或密钥管理服务由部署流程临时注入而不是躺在磁盘文件里。审计意识定期用 CI 中的密钥扫描如 git 历史扫描兜底配合项目自带的 安全响应流程 处理已确认的泄露。排障速查表这些报错先查哪症状大概率原因处理动作生产启动直接抛错未设置BETTER_AUTH_SECRET生成 32 位以上随机密钥并注入环境变量登录回调 404 / 链接打不开BETTER_AUTH_URL与真实域名不一致核对 URL 的协议、域名、端口三者改了变量没生效开发服务器缓存了旧环境变量重启 dev server 后再验证clientId在运行时为 undefined变量名拼写不一致如多/少一个下划线对照.env.example逐字符核对浏览器 Network 里看到 secret敏感变量误加了NEXT_PUBLIC_前缀去掉前缀只保留服务端读取排查时记住框架的读取顺序BETTER_AUTH_SECRET→AUTH_SECRET。如果两个变量同时存在但值不同以第一个为准这也是多人调试时我明明改了怎么没变的常见根源。下一步与延伸阅读环境变量只是 Better Auth 的地基——两个核心变量跑通认证第三方凭据接上社交登录版本化 secrets 保证轮换不停服。建议先把上面的排障速查表收藏上线时照着加固清单逐项打勾。安装与完整配置流程installation.mdx官方 demo 的环境变量模板demo/nextjs/.env.example安全响应与披露政策SECURITY.md密钥 CLI 实现packages/cli/src/commands/secret.ts环境变量读取实现packages/core/src/env/env-impl.ts想动手实践的话可以克隆完整仓库里面有可直接运行的 Next.js / Expo / Electron 等全套示例git clone https://gitcode.com/GitHub_Trending/be/better-auth【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Better Auth 环境变量避坑指南：2 个核心变量 + 密钥轮换一次配好
Better Auth 环境变量避坑指南2 个核心变量 密钥轮换一次配好【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-authBetter Auth 是最全面的认证框架Authentication Framework支持邮箱密码、社交登录、Passkey、SSO 等完整能力。而这一切的起点是项目根目录一个不起眼的.env文件——BETTER_AUTH_SECRET和BETTER_AUTH_URL配错或漏配轻则登录回调 404重则生产密钥泄露。本文按本地跑通 → 接入第三方 → 进阶配置 → 排障的真实工作流把 Better Auth 环境变量该知道的都讲清楚。最小可用配置两个变量就能跑起来BETTER_AUTH_SECRET会话加密的根钥匙这个密钥用于会话加密、令牌签名和哈希是整个认证体系信任链的起点。框架的查找逻辑很直白先读BETTER_AUTH_SECRET找不到会退回兼容变量AUTH_SECRET开发环境下两者都缺省会用一个内置默认值兜底但生产环境未设置会直接抛错拒绝启动——这是框架故意做的防线别绕过它。对密钥的要求只有一条至少 32 个字符、高熵随机。别用密码管理器里手敲的看起来很长的口令用工具生成# 方式一openssl 一行搞定 openssl rand -base64 32 # 方式二Better Auth CLI 的 secret 子命令内部是 32 字节随机数 npx authlatest secretCLI 会直接打印出一行可以粘贴进.env的完整内容。实现细节可以看 secret 命令源码环境变量读取逻辑在 env-impl.ts。BETTER_AUTH_URL回调地址和 Cookie 的基准OAuth 回调 URL、邮件里的链接、Cookie 的作用域全部基于这个 URL 拼接。本地开发指向本机地址即可# 根密钥32 位以上高熵随机字符串 BETTER_AUTH_SECRETyour-32-char-high-entropy-secret # 应用基础 URL BETTER_AUTH_URLhttp://localhost:3000如果没显式设置baseURL框架会按BETTER_AUTH_URL、NEXT_PUBLIC_BETTER_AUTH_URL等顺序去环境变量里找。Next.js 项目两个名字都能生效但建议统一用BETTER_AUTH_URL避免团队里混用两套。配好后实例化认证服务放在auth.ts或lib/auth.ts等位置导出变量名为authimport { betterAuth } from better-auth; export const auth betterAuth({ // secret 和 baseURL 已自动从环境变量读取这里只需补数据库等配置 database: { /* 数据库配置 */ }, });接入社交登录第三方凭据怎么放开启 GitHub 登录只需要一对凭据在socialProviders里引用环境变量即可export const auth betterAuth({ socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, }, });GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret凭据放置有三条纪律都是生产事故高发区服务端变量绝不进浏览器在 Next.js 里只有NEXT_PUBLIC_前缀的变量才会被打包进客户端。clientSecret这类值绝不能加该前缀否则等于把钥匙贴在了公网。clientId 可以放宽clientSecret 不行参考官方 demo 的做法NEXT_PUBLIC_GOOGLE_CLIENT_ID给客户端用GOOGLE_CLIENT_SECRET只留在服务端模板见 demo/nextjs/.env.example。禁止硬编码clientSecret: abc123写死在代码里一旦仓库公开或交接就全泄露敏感值一律走环境变量生产环境再叠加 CI/CD 的密钥管理注入。进阶配置密钥轮换与多环境分层用版本化 secrets 做无损轮换密钥泄露或定期换钥是迟早的事而直接替换BETTER_AUTH_SECRET会让存量加密数据全部无法解密。Better Auth 提供了BETTER_AUTH_SECRETS复数解决这个问题按版本组织多个密钥第一项是新写入用的当前密钥其余仅作解密旧数据# 格式版本号:密钥,版本号:密钥第一个为当前加密密钥 BETTER_AUTH_SECRETS2:新密钥base64,1:旧密钥base64轮换时把新密钥作为第一项写入存量会话用旧版本密钥继续解密过渡期结束后再移除最旧的版本。这是改密钥不停服的关键机制配置项说明见 secrets 选项。按环境分层管理配置文件别用一个.env打天下按环境隔离.env团队共享的基础配置非敏感值.env.local本机覆盖优先级高于.env个人数据库地址放这里.env.example提交到仓库的变量清单模板只有 key 没有 value新人照着填优先级从高到低系统环境变量 →.env.local→.env。CI/CD 平台注入的密钥属于系统环境变量天然能覆盖仓库里的文件。另一个容易忽略的进阶项如果应用挂在反向代理后面且没有显式配置baseURL需要谨慎使用trustedProxyHeaders从请求头推断域名——官方文档明确提示配置不当会引入安全漏洞能用静态baseURL或allowedHosts白名单就优先用后者。安全加固别让密钥流向版本库密钥生成得再好管不住出口等于白搭。上线前对照这份清单过一遍版本控制排除.env/.env.local必须在.gitignore中仓库里只保留.env.example模板。已经不小心提交过密钥的正确姿势是先换密钥、再清理历史光删文件没用。文件权限收紧生产服务器的.env建议chmod 600仅所有者可读写防止同机其他账号读取。密钥托管上规模后把核心密钥放进云厂商的 Secrets Manager 或密钥管理服务由部署流程临时注入而不是躺在磁盘文件里。审计意识定期用 CI 中的密钥扫描如 git 历史扫描兜底配合项目自带的 安全响应流程 处理已确认的泄露。排障速查表这些报错先查哪症状大概率原因处理动作生产启动直接抛错未设置BETTER_AUTH_SECRET生成 32 位以上随机密钥并注入环境变量登录回调 404 / 链接打不开BETTER_AUTH_URL与真实域名不一致核对 URL 的协议、域名、端口三者改了变量没生效开发服务器缓存了旧环境变量重启 dev server 后再验证clientId在运行时为 undefined变量名拼写不一致如多/少一个下划线对照.env.example逐字符核对浏览器 Network 里看到 secret敏感变量误加了NEXT_PUBLIC_前缀去掉前缀只保留服务端读取排查时记住框架的读取顺序BETTER_AUTH_SECRET→AUTH_SECRET。如果两个变量同时存在但值不同以第一个为准这也是多人调试时我明明改了怎么没变的常见根源。下一步与延伸阅读环境变量只是 Better Auth 的地基——两个核心变量跑通认证第三方凭据接上社交登录版本化 secrets 保证轮换不停服。建议先把上面的排障速查表收藏上线时照着加固清单逐项打勾。安装与完整配置流程installation.mdx官方 demo 的环境变量模板demo/nextjs/.env.example安全响应与披露政策SECURITY.md密钥 CLI 实现packages/cli/src/commands/secret.ts环境变量读取实现packages/core/src/env/env-impl.ts想动手实践的话可以克隆完整仓库里面有可直接运行的 Next.js / Expo / Electron 等全套示例git clone https://gitcode.com/GitHub_Trending/be/better-auth【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考