快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-neon` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-neon
bunx cap sync

Neon 配置

1. 启用 Neon 身份验证 在你的分支上（控制台 > 身份验证，或 neon neon-auth enable).
2. 启用 API 数据 在同一分支上，如果你需要数据库辅助功能（控制台 > Data API，提供商选 Neon Auth）。
3. 复制 认证 URL 以及 API 数据 URL 从控制台获取。

Neon Auth 仅接受来自受信任来源的请求。默认情况下 localhost 受信任，插件会发送 Origin: https://localhost，因此新分支无需改动即可使用。如果你关闭了 localhost，请将你的某个域名添加为受信任域名，并把它作为 origin 改为 initialize().

iOS 配置

邮箱和 OTP 登录无需额外配置。该插件使用 URLSession 和 Keychain，没有第三方依赖。

对于 OAuth，请设置 redirectTo 为受信任的 https Universal Link，用于打开您的应用。Neon Auth 会将自定义 URL scheme 视为 redirectTo。如果您在应用中使用自定义 scheme，请托管一个受信任的 HTTPS 回调页面，将 neon_auth_session_verifier 查询参数转发到该 scheme。

Android 配置

邮箱和 OTP 登录无需额外配置。该插件支持 Capacitor 8 的默认最低 SDK 24（Android 7.0）。

对于 OAuth，请设置 redirectTo 为受信任的 https 用于打开应用的 App Link。Neon Auth 拒绝将自定义 URL scheme 作为 redirectTo。如果应用中使用自定义 scheme，请托管一个受信任的 HTTPS 回调页面，将 neon_auth_session_verifier 查询参数转发至该 scheme。

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 初始化一次: 在应用启动时运行 setup。
• OAuth 重定向：Neon Auth 仅接受受信任的 https URL，用于 redirectTo （纯 http 仅用于受信任的 localhost 本地测试）。自定义 URL scheme 会被拒绝。请使用 Universal Link 或 App Link，或使用将 neon_auth_session_verifier 查询参数转发到您应用 URL scheme 的受信任 HTTPS 页面。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

初始化客户端

import { CapacitorNeon } from '@capgo/capacitor-neon';

await CapacitorNeon.initialize({
  authUrl: 'https://ep-xxx.neonauth.us-east-2.aws.neon.tech/neondb/auth',
  dataApiUrl: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
});

登录并获取 JWT

const { session, user } = await CapacitorNeon.signInWithPassword({
  email: 'user@example.com',
  password: 'password123',
});

console.log('User', user?.id);
console.log('JWT available', Boolean(session?.accessToken));

注册

如果 注册时验证邮箱 已为您的分支启用， signUp() 在用户确认邮件中的 code 之前，不会返回会话。

import { CapacitorNeon } from '@capgo/capacitor-neon';

const { session } = await CapacitorNeon.signUp({
  email: 'newuser@example.com',
  password: 'password123',
  name: 'John Doe',
});

if (!session) {
  await CapacitorNeon.verifyOtp({
    email: 'newuser@example.com',
    token: '123456',
    type: 'signup',
  });
}

监听 Auth 状态变化

const listener = await CapacitorNeon.addListener('authStateChange', ({ event, session }) => {
  console.log('Auth event', event);
  console.log('Current JWT available', Boolean(session?.accessToken));
});

// Call listener.remove() when the screen unmounts.

将 Native Auth 与 neon-js 搭配

使用此模式时，请安装 JavaScript 客户端：

bun add @neondatabase/neon-js

import { CapacitorNeon } from '@capgo/capacitor-neon';
import { createClient } from '@neondatabase/neon-js';

const neon = createClient({
  dataApi: {
    url: 'https://ep-xxx.apirest.us-east-2.aws.neon.tech/neondb/rest/v1',
    getToken: async () => (await CapacitorNeon.getSession()).session?.accessToken ?? null,
  },
});

const { data } = await neon.from('table').select('*');
console.log('Row count', data?.length ?? 0);

Native 数据库辅助函数

const { data, error } = await CapacitorNeon.select({
  table: 'users',
  columns: 'id, name, email',
  filter: { active: true },
  limit: 10,
  orderBy: 'created_at',
  ascending: false,
});

if (error) {
  console.error('Select failed', error);
} else {
  console.log('Rows returned', data?.length ?? 0);
}

在无人登录时，数据库辅助函数会使用匿名的 Data API token，因此针对该 anonymous 角色的行级安全策略将会生效。

推荐用法

• 使用此插件进行身份验证和会话管理。
• 将高级查询保留在 @neondatabase/neon-js.
• 保留 对象存储 以及 AI 网关 在 Neon Function 或您自己的 API 中调用。两者都使用分支凭证，这些凭证必须保留在应用 bundle 之外。在访问这些服务之前，请先对 Neon Functions 的请求进行身份验证；它们的 URL 是公开的。
• 在需要时，将原生 JWT 传递给 JavaScript 客户端、Neon Functions 或您自己的 API。

从入门指南继续

如果你正在使用 快速入门 要规划原生插件工作，请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 查看添加或更新插件中的实现细节， Ionic Enterprise 插件替代方案 查看 Ionic Enterprise 插件替代方案中的产品工作流，以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。