neon-auth 是什么？
neon-auth 是 neondatabase/agent-skills 仓库中的一个 Agent Skill，面向 Claude Code、Cursor、Codex 等支持 Agent Skills 标准的 AI 编码助手。它的官方描述非常直接：“Sets up Neon Auth for your application. Configures authentication, creates auth routes, and generates UI components.”
但它的真正价值不在“生成代码”，而在决策逻辑。Neon Auth 在 2025 年底经历了一次重大重构，从“外部身份提供方 + Webhook 同步”的模式，切换到了基于 Better Auth、身份数据直接存在 Neon 数据库里的新架构[citation:2][citation:5]。这意味着用户、会话、组织、OAuth 配置全部住在你数据库的 neon_auth schema 里，跟着 Branch 一起复制、一起隔离。
neon-auth Skill 的作用就是让 AI 理解这个架构转变，并在你的项目里做出正确的选择：什么时候该用 Managed Better Auth，什么时候该保留现有的身份系统，什么时候该走自托管路线。
neon-auth 的主要功能
身份系统决策检查。在动任何代码之前，Skill 要求先检查项目现有的身份配置和登录功能需求。官方 SKILL.md 中的决策表非常明确：没有认证 → 默认 Managed Better Auth；已有 Better Auth → 保留；用户要求从 Supabase Auth 迁移 → 走 Managed Better Auth 迁移路径；已有 Clerk、Auth.js 或其他能工作的 IdP → 除非用户要求，否则保留[citation:4]。
Managed Better Auth 配置。对于新项目或明确需要迁移的项目，Skill 引导 AI 通过 neon.ts 配置文件声明 auth: true，然后运行 neon deploy。它明确区分了“在配置里声明 auth”和“实际实现登录”——auth: true 不是登录功能本身，只是启用了 Managed Auth 服务[citation:4]。
登录功能实现。Managed Auth 启用后，Skill 加载 guides/nextjs-setup.md 或 guides/react-spa-setup.md，按步骤生成认证路由、客户端配置和 UI 组件。它优先推荐使用 AuthView 组件而不是手写表单，覆盖登录、注册、忘记密码、魔法链接等路径[citation:6][citation:15]。
插件支持矩阵检查。Neon Auth 是 Managed Better Auth，不接受直接传入 Better Auth 插件。Skill 要求 AI 检查所需的插件（MFA、Passkeys、SSO 等）是否在 Neon 支持的子集内。目前支持的包括 Admin、Email OTP、JWT、Magic Link、Organization、Open API、Phone Number[citation:4][citation:19]。
neon-auth 的核心特色
“不要为了用 Postgres 而换掉身份系统”。这是 Skill 最明确的纪律。官方原文：“A supplied DATABASE_URL is not a reason to change identity. Adding a Neon Function is not a reason to change identity.”[citation:4] 很多开发者在迁移数据库时顺手把认证也换了，但这个 Skill 阻止这种“顺手”行为。
身份数据跟着 Branch 走。这是 Neon Auth 与所有传统认证服务的根本区别。Clerk、Auth0、Supabase Auth 都是全局单例，你的 staging 和 production 共享同一个认证实例。Neon Auth 把用户、会话、OAuth 配置全部存在数据库里，创建 Branch 时整个 neon_auth schema 被复制，每个 Branch 有独立的认证端点[citation:2][citation:14]。Skill 让 AI 理解这个机制，并在配置时利用它。
对“已有系统”的尊重。如果你已经在用 Clerk 并且工作正常，neon-auth 不会尝试说服你迁移。它的默认行为是保留。只有当你明确说“帮我从 Supabase Auth 迁移到 Neon Auth”时，它才会走迁移路径[citation:4]。
Managed 与自托管的清晰边界。Managed Auth 有功能限制（不支持自定义插件、不支持 IP Allow、仅限 AWS 区域）。Skill 在启用前要求确认这些前置条件，如果不满足，它会引导你走自托管 Better Auth 路线，而不是强行配置一个不工作的 Managed 实例[citation:4]。
neon-auth 可以用来做什么？
给新的 Next.js 或 React 项目加登录。你刚用 Neon 建了一个 Postgres 数据库，需要一个认证系统。Skill 会默认引导你启用 Managed Better Auth，生成登录路由、UI 组件和会话管理代码。
从 Supabase Auth 迁移。你明确要求把认证从 Supabase 迁移到 Neon。Skill 加载迁移指南，处理用户数据、OAuth 配置和会话的转移。
利用 Branch 做认证测试。你想在 preview 环境里用生产数据测试一个新的角色权限系统。Neon Auth 的身份数据跟着 Branch 复制，你的 preview 环境天然拥有和生产一样的用户和角色，不需要手动造测试账号[citation:14]。
不适合的场景：你只想用 Neon 的 Postgres，不想动现有认证（Skill 不会逼你换）；你需要 Neon 不支持的自定义 Better Auth 插件（Managed 不支持，需要走自托管路线）；以及你不涉及任何认证逻辑的纯数据项目。
neon-auth 适合哪些人？
- 用 Neon 做后端的新项目开发者：还没有认证系统，需要一个和数据库深度集成、支持 Branching 的方案。
- 从 Supabase 迁移到 Neon 的团队：需要把 Auth 也一起迁移过来。
- 已经在用 Better Auth 但想尝试 Managed 版本的人：可以评估 Neon 的托管服务是否满足需求。
- 需要 preview 环境有真实认证数据的团队：Branching Auth 让 staging 和 preview 环境拥有和生产一致的用户和权限。
不太适合：已经在用 Clerk 或 Auth.js 并且满意的项目（Skill 会建议保留）；需要 Managed Auth 不支持的插件的人；以及不使用 Neon 数据库的项目。
neon-auth 如何安装？
方式一：通过 Neon CLI 安装（推荐）
neon skills -s neon-authNeon CLI 会交互式地检测你的 Agent，确认后写入技能文件。加 --global 可全局安装。
方式二：通过 skills CLI 安装
npx skills add neondatabase/agent-skills -s neon-auth -y-y 跳过确认，-s 选择特定技能，-g 全局安装。
方式三：Claude Code 插件市场
/plugin marketplace add neondatabase/agent-skills
/plugin install neon-postgres@neon这会安装 Neon 全套技能和 Neon MCP Server。
前置条件：Managed Auth 仅支持 AWS 区域，且不能启用 IP Allow 或 Private Networking。Skill 会在配置前检查这些条件[citation:4]。
neon-auth 怎么使用？
基本流程（Managed Auth 新项目）：
- 在项目中创建一个
neon.ts配置文件，声明auth: true。 - 运行
neon deploy启用 Managed Auth。 - 运行
neon neon-auth status确认状态。 - Skill 自动加载框架对应的指南（Next.js 或 React SPA），生成认证路由、客户端配置和 UI 组件。
- 检查环境变量：
NEON_AUTH_BASE_URL和NEXT_PUBLIC_NEON_AUTH_URL。
推荐的触发方式：
用 neon-auth 技能帮我给这个 Next.js 项目加上 Neon Auth 登录，先检查我有没有现成的认证系统。或者：
我现在的项目用 Supabase Auth，想迁移到 Neon Auth，用 neon-auth 技能处理。neon-auth 使用技巧
先让 Skill 检查，不要直接让它“装”认证。neon-auth 的决策逻辑是它的核心价值。如果你直接说“帮我加 Neon Auth”，它可能会跳过检查。更好的说法是：“先检查我的项目有没有现成的认证系统，再决定要不要用 Neon Auth。”[citation:4]
Managed Auth 的插件限制要提前确认。如果你需要 MFA、Passkeys、SSO 或自定义 Better Auth 插件，Managed Auth 不支持。Skill 会让你检查插件矩阵，不要跳过这一步[citation:4]。
利用 Branching 做认证测试。如果你在 preview 环境测试登录流程，不需要手动创建测试用户。从生产 Branch 复制一份，neon_auth schema 里的用户、会话、OAuth 配置全部跟着过来，直接可以用[citation:14]。
生产环境需要自定义 SMTP。Managed Auth 的起步配置使用共享 SMTP（auth@mail.myneon.app），适合开发。上线前需要配置自己的邮件服务商，Skill 会提醒你查看 production checklist[citation:4]。
neon-auth 收费吗？
Skill 免费且开源。neon-auth 是 neondatabase/agent-skills 仓库的一部分，MIT 许可证。Skill 本身不收取费用。
Neon Auth 本身包含在 Neon 的套餐中。官方明确说 “Neon Auth is available on all plans, including Free”[citation:2]。你只需要为 Neon 数据库的使用付费（免费套餐有额度限制），以及为 AI 编码助手支付订阅费用。
neon-auth 的优点与缺点
| 维度 | 优点 | 缺点 |
|---|---|---|
| 决策逻辑 | 先检查再决定，不强迫已有认证的项目迁移 | 需要用户理解“保留现有系统”也是一种正确结果 |
| Branching 集成 | 身份数据跟着数据库 Branch 复制，preview 环境有真实用户 | 仅支持 AWS 区域，不支持 IP Allow 和 Private Networking |
| Better Auth 基础 | 基于成熟的 Better Auth，API 和 schema 一致 | Managed 版本不支持自定义插件；插件子集有限 |
| 开箱即用 | 包含邮件验证、OTP、魔法链接、密码重置（共享 SMTP 起步） | 生产环境需要自己配 SMTP；起步 SMTP 不适合上线 |
| 生态一致性 | 与 Neon Data API、RLS 深度集成，JWT 自动验证 | 如果已经用了 Clerk/Auth.js，迁移收益需要评估 |
neon-auth 与同类工具对比
vs Clerk。Clerk 是功能最完整的第三方认证服务，UI 组件丰富、支持 MFA/Passkeys/SSO、有独立的管理面板。Neon Auth 的优势在数据位置：身份数据在你的 Postgres 里，Branch 时跟着复制，RLS 可以直接引用。如果你的项目重度依赖 Neon 的 Branching 工作流，Neon Auth 的集成度更高。如果你需要 Clerk 的完整功能和成熟生态，保留 Clerk 是合理的。
vs Supabase Auth。Supabase Auth 和 Supabase 数据库绑定。Neon Auth 的思路相同（身份在数据库里），但绑定的是 Neon 的 Branching 机制。如果你从 Supabase 迁移到 Neon，Neon Auth 提供了迁移指南[citation:4]。
vs 自托管 Better Auth。自托管给你完全的控制权（任意插件、自定义逻辑），但你需要自己管理服务器、邮件、会话存储。Neon Auth 是 Managed 版本，省掉了运维，但牺牲了插件自由度。Skill 会在 Managed 不满足需求时引导你走自托管路线[citation:4]。
neon-auth 常见问题 FAQ
Q：neon-auth 会强制我换掉现有的 Clerk/Auth.js 吗？
不会。Skill 的决策表明确说：已有能工作的 IdP → 除非用户要求，否则保留[citation:4]。
Q：Neon Auth 的数据存在哪里？
存在你 Neon 数据库的 neon_auth schema 里，包括用户、会话、组织、OAuth 配置和 JWKS[citation:2][citation:5]。
Q：Branch 时认证数据会跟着复制吗？
会。每个 Branch 有独立的认证端点，用户和会话在 Branch 时被复制。这是 Neon Auth 与 Clerk/Auth0 的根本区别[citation:2][citation:14]。
Q：Managed Auth 支持哪些插件？
目前支持 Admin、Email OTP、JWT、Magic Link、Organization、Open API、Phone Number。MFA、Passkeys、SSO、自定义插件不支持[citation:19]。
Q：免费套餐能用 Neon Auth 吗？
能。官方明确说 “Neon Auth is available on all plans, including Free”[citation:2]。
Q：生产环境需要额外配置吗？
需要。起步使用共享 SMTP，生产需要配置自己的邮件服务商。另外需要确认项目在 AWS 区域，且没有启用 IP Allow 或 Private Networking[citation:4]。
neon-auth 综合评价
neon-auth 解决的是一个架构层面的决策问题：身份系统应该放在哪里，以及它应该和数据库保持什么关系。
传统认证服务（Clerk、Auth0、Supabase Auth）的设计前提是“一个认证实例服务多个环境”。这在“一个生产 + 一个 staging”的时代是合理的。但当你的工作流变成“每个 PR 一个 preview 环境、每个 feature 一个数据库 Branch”时，认证变成了唯一不跟着 Branch 走的组件。你的数据库复制了，用户数据没复制；你的 schema 迁移了，角色没迁移。Neon Auth 的设计选择是：把身份数据放进数据库，让它跟着 Branch 一起走。
neon-auth Skill 的价值不在于“生成登录代码”——那是最简单的部分。它的价值在于阻止错误决策：不要因为换了数据库就换认证，不要因为用 Neon 就迁移一个工作正常的 Clerk 系统。它的决策表明确、边界清晰，让 AI 在正确的时机做正确的事。
它的局限在于 Managed Auth 的功能边界。如果你需要 MFA、Passkeys、SSO 或深度自定义，Managed Auth 不满足需求，Skill 会引导你走自托管 Better Auth 路线。但对于大多数需要“标准登录 + 数据库集成 + Branching 支持”的项目，Neon Auth 提供了一个省心且架构合理的方案。
◯ 评论 0