# @alchemy\.run/better-auth 中文文档

规范地址：https://npmcn.com/package/%40alchemy.run/better-auth/

版本：2\.0\.0-beta\.85
npm 元数据更新时间：2026-11-02T21:04:30.244Z
中文译文更新时间：2026-11-05T17:49:32.281Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alchemy.run/better-auth
原文对照：https://npmcn.com/package/%40alchemy.run/better-auth/?lang=original
项目主页：https://alchemy.run/
源码仓库：https://github.com/alchemy-run/alchemy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：252 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：pg ^8\.22\.0，effect ^4\.1\.0，kysely ^0\.29\.4，mysql2 ^3\.24\.2，alchemy 2\.0\.0-beta\.85，better-auth ^1\.7\.5，drizzle-orm 1\.0\.0-rc\.5，@alchemy\.run/aws 2\.0\.0-beta\.85，@distilled\.cloud/aws 1\.0\.0-rc\.18，@alchemy\.run/cloudflare 2\.0\.0-beta\.85，@neondatabase/serverless ^1\.0\.1，@cloudflare/workers-types 5\.20261026\.1，@better-auth/drizzle-adapter ^1\.7\.5
- 首次发布：2026-04-10T02:34:02.022Z
- 最新版本发布：2026-11-02T21:04:29.920Z
- 近 30 天下载量：135215（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：90（近 12 个月 90 个）

## 中文简介

为Alchemy更好的Auth集成.

## 安装

```sh
npm install @alchemy.run/better-auth
```

也可以使用：`pnpm add @alchemy.run/better-auth`、`yarn add @alchemy.run/better-auth`、`bun add @alchemy.run/better-auth`

## README

# @alchemy.run/better-auth (中文(简体) )

[更好的认证](https://better-auth.com/) 页:1 [炼金术](https://alchemy.run/) ——一个效果-内在包装器外加每个平台可插接的数据库层.

跟着 [六段教学](https://alchemy.run/better-auth/tutorial/part-1) 用于构建浏览器的签名, Effect HTTP API 中间软件,以及 GitHub 认证. 见 [登录提供者](https://alchemy.run/better-auth/sign-in-providers) 财务报告和审定财务报表 [数据库指南](https://alchemy.run/better-auth/databases) 其他整合.

```typescript
import { BetterAuth } from "@alchemy.run/better-auth";
import { CloudflareD1 } from "@alchemy.run/better-auth/CloudflareD1";
import * as Cloudflare from "@alchemy.run/cloudflare";

export const AuthDb = Cloudflare.D1.Database("AuthDb");

export default class Api extends Cloudflare.Worker<Api>()(
  "Api",
  { main: import.meta.url, compatibility: { flags: ["nodejs_compat"] } },
  Effect.gen(function* () {
    const auth = yield* BetterAuth({
      basePath: "/auth",
      emailAndPassword: { enabled: true },
    });

    return {
      fetch: Effect.gen(function* () {
        const request = yield* HttpServerRequest;
        if (request.url.startsWith("/auth")) {
          return yield* auth.fetch; // the Better Auth HTTP surface
        }
        const session = yield* auth.getSession(); // null when anonymous
        return yield* HttpServerResponse.json({ user: session?.user ?? null });
      }),
    };
  }).pipe(Effect.provide(CloudflareD1(AuthDb))),
) {}
```

你得到的东西是:

-   **`yield* BetterAuth(options)`** ——满 `Auth<Options>` 类型推论: 通过的插件 `auth.api`, (中文(简体) ), `Session` 类型来自选项。 没有标签,没有铸币.
-   **`auth.api.*`** – 每一个更好的 Auth 端点作为效果键入 `BetterAuthApiError` 失败( e)`status`, (中文(简体) ), `statusCode`, (中文(简体) ), `body.code`,以及 `headers` _包括_ 页:1 `set-cookie` 标题更好调用隐藏在符号上。 无`APIError` 抛掷是缺陷.
-   **`auth.fetch`** - 炼金术 `HttpEffect` 为更好的Auth线路服务;在Cloudflare Workers和AWS Lambda的工程不变.
-   **`auth.getSession()`** - 从环境请求中输入会话查询(或明确 `Headers`页:1 `null` 为匿名.
-   **`auth.auth`** - 原始执行 `Auth` 成为逃生舱.
-   **部署时自动迁移计划** - 内部炼金术(包括插件) `alchemy deploy`,仅在计划或目标数据库发生变化时重新运行。 选择退出 `migrate: false`。 。 。 .
-   **管理机密** —— 说 `secret` 默认为稳定的自动设置 `Alchemy.Random` 值绑入主机环境.

数据库是您提供的关于周围杂效的图层 。 选择您环境的最佳层 ~ 数据库配对 — HTTP/ 无服务器驱动程序, TCP驱动程序作为倒置:

| 运行时间 | 数据库 | 层 | 运输 |
| --- | --- | --- | --- |
| 云花岗工人 | D1级 | `CloudflareD1` | 本地绑定 |
| Cloudflare 工人/ AWS Lambda | 霓虹 | `Neon` | 无服务器驱动程序( WebSocket) |
| AWS 兰布达 | 奥罗拉 | `AuroraDataApi` | RDS 数据 API (HTTPS, IAM) |
| 云花岗工人 | 任何 TCP 邮递/ MySQL | `CloudflareHyperdrive` | 通过超驱动程序集合 TCP |
| 任何带有套接字的地方 | 任何邮资 | `Postgres` | `pg` TCP 常规程序 |
| 任何带有套接字的地方 | 任何 MySQL(例如: 星球标本) | `MySQL` | `mysql2` TCP 常规程序 |
| 圆包( dev/ tests) | 本地文件 | `SQLite` | `bun:sqlite` |
| 测试 | 记忆 | `Memory` | —— 说 |
| 带上你的 | 你的"滴滴" db | `Drizzle` |  |

每层路由通过炼金术的捆绑系统运行时间访问——本土捆绑(D1,Hyperdrive,RDS Data API IAM grants)或主机-环境输出捆绑(连接字符串)——从不使用手接管活字 vars.

## 云纹 D1

本地 D1 在运行时绑定; 迁移在部署时运行于 D1 HTTP API 上( 并针对本地模拟器) `alchemy dev`) (中文(简体) ).

```typescript
import { CloudflareD1 } from "@alchemy.run/better-auth/CloudflareD1";
import * as Cloudflare from "@alchemy.run/cloudflare";

export const AuthDb = Cloudflare.D1.Database("AuthDb");

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(CloudflareD1(AuthDb)));
```

## 霓虹

Neon的无服务器驱动程序从边缘说 WebSocket —— 无超驱动程序, 无 `pg`没有 TCP 套接字。 工人和Lambda的最佳配对`@neondatabase/serverless` 是一个可选的对等点).

```typescript
import { Neon as NeonDatabase } from "@alchemy.run/better-auth/Neon";
import * as Neon from "@alchemy.run/neon";

export const AuthDb = Neon.Project("AuthDb");

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(
  Effect.provide(
    Layer.unwrap(Effect.map(AuthDb, (db) => NeonDatabase(db.connectionUri))),
  ),
);
```

## 奥罗拉 (RDS Data API)

以 IAM auth 为主的 SQL over HTTPS – 没有为 Lambda 所附加的 VPC , 没有驱动器, 没有池. 运行时间访问流经 `AWS.RDSData.*` 约束(授予) `rds-data:*` + 键 `secretsmanager:GetSecretValue` 在主机上); 部署时间迁移使用与堆栈证书相同的数据 API. `kysely` 财务报告和审定财务报表 `@distilled.cloud/aws` 是可选的同龄人.

```typescript
import { AuroraDataApi } from "@alchemy.run/better-auth/AuroraDataApi";
import * as AWS from "@alchemy.run/aws";

export const Db = AWS.RDS.Aurora("AuthDb", {
  subnetIds: network.privateSubnetIds,
  securityGroupIds: [securityGroup.groupId],
  // the Data API is enabled by default
});

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(AuroraDataApi(Db, { database: "postgres" })));
```

## 云浮超驱动

通过Hyperdrive连接来集合 Postgres(或 MySQL). Hyperdrive 的连接字符串只存在于工作间,所以通过 _来源_ 用于部署时间迁移的 URL( 或省略) `migrate` 跳过它们.

```typescript
import { CloudflareHyperdrive } from "@alchemy.run/better-auth/CloudflareHyperdrive";

const branch = yield* Neon.Branch("auth-db", { project });
const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("auth-hd", {
  origin: branch.origin,
});

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(
  Effect.provide(
    CloudflareHyperdrive(hyperdrive, { migrate: branch.connectionUri }),
  ),
);
```

## Postgres( 基因TCP)

您拥有连接字符串的 Postgres 的倒置: Planet Scale Postgres ()`role.connectionUrl`(原始内容存档于2013-10-12). Prisma Postgres (英语)`connection.databaseUrl`),VPC内部的RDS,或字面URL. 一个 `pg` 每次执行的池,活动结束后关闭. `pg` 是一个可选的同伴依赖。 (预选 `Neon`编号 :`AuroraDataApi`编号 :`CloudflareHyperdrive` 当他们符合你的对。 )

```typescript
import { Postgres } from "@alchemy.run/better-auth/Postgres";

const project = yield* Neon.Project("AuthDb");

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(Postgres(project.connectionUri)));
```

资源产出在运行时部署并读取时被绑入主机环境;同一源驱动部署-时间迁移(覆盖 `migrate:`禁用 `migrate: false`) (中文(简体) ).

## MySQL( 通用 TCP )

与 Postgres 的形状相同 `mysql2` (可选对等点): Planet Scale MySQL, Hyperdrive MySQL 起源, RDS MySQL. Planet Scale 需要 TLS —— 在 URL 中通过它 `ssl` 查询参数.

```typescript
import { MySQL } from "@alchemy.run/better-auth/MySQL";

const password = yield* Planetscale.MySQLPassword("auth-db", { database, role: "admin" });
const url = `mysql://${password.username}:...@${password.host}/${database.name}?ssl=${encodeURIComponent('{"rejectUnauthorized":true}')}`;

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(MySQL(url)));
```

## AWS 兰布达

不需要专用主机层—— `auth.fetch` 是可携带的主机。 从 Lambda 函数 URL 中提供与您目标匹配的数据库层: `AuroraDataApi` 为奥罗拉, `Neon` 或通用的 `Postgres`编号 :`MySQL` (蓝巴达的TCP司机需要) `build: { install: ["pg"] }` 所以有npm布局的动态进口驾驶船.

```typescript
import * as Lambda from "@alchemy.run/aws/Lambda";
import { Neon as NeonDatabase } from "@alchemy.run/better-auth/Neon";

export const AuthDb = Neon.Project("AuthDb");

export class AuthFunction extends Lambda.Function<Lambda.Function>()("AuthFunction") {}

export default AuthFunction.make(
  // scrypt password hashing needs headroom over the 128 MB default
  { main, url: true, memorySize: 512, timeout: Duration.seconds(30) },
  Effect.gen(function* () {
    const auth = yield* BetterAuth({
      basePath: "/auth",
      emailAndPassword: { enabled: true },
    });
    return { fetch: /* route /auth/* to auth.fetch */ };
  }).pipe(
    Effect.provide(
      Layer.unwrap(Effect.map(AuthDb, (db) => NeonDatabase(db.connectionUri))),
    ),
  ),
);
```

## SQLite(地方发展)

`bun:sqlite`\- 在包跑时进行开发和测试.

```typescript
import { SQLite } from "@alchemy.run/better-auth/SQLite";

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(SQLite(".alchemy/auth.sqlite")));
```

## 内存( 测试)

记忆适配器;没有什么持续,不需要移民.

```typescript
import { Memory } from "@alchemy.run/better-auth";

Effect.gen(function* () {
  const auth = yield* BetterAuth({
    emailAndPassword: { enabled: true },
    secret: "test-secret",
  });
  // ...
}).pipe(Effect.provide(Memory()));
```

## 滴水龙头

通过 Better Auth 关系 v2 带回自己的 Drizzle 数据库 `drizzleAdapter` (可选对等者) `drizzle-orm` 财务报告和审定财务报表 `@better-auth/drizzle-adapter`) (中文(简体) ). Schema是你的——这个层没有自动迁移。 配置 CLI 认证实例 `@better-auth/drizzle-adapter/relations-v2`运行 `npx auth@1.7.5 generate --config ./auth.cli.ts`。通过 `--adapter drizzle` 选择遗留生成器,而不是配置的适配器.

```typescript
import { Drizzle } from "@alchemy.run/better-auth/Drizzle";
import { drizzle } from "drizzle-orm/node-postgres";
import * as schema from "./auth-schema.ts";
import { relations } from "./app-schema.ts";

const db = drizzle({
  client: pool,
  relations: { ...relations, ...schema.authRelations },
});

Effect.gen(function* () {
  const auth = yield* BetterAuth({ emailAndPassword: { enabled: true } });
  // ...
}).pipe(Effect.provide(Drizzle(db, { provider: "pg", schema })));
```

## 处理错误

```typescript
const result = yield* auth.api
  .signInEmail({ body: { email, password } })
  .pipe(
    Effect.catchTag("BetterAuthApiError", (error) =>
      error.statusCode === 401
        ? Effect.succeed(null)         // wrong credentials
        : Effect.fail(error),
    ),
  );
```

`error.toResponse()` 使故障与更好的Auth完全相同(状态+JSON正体+合并头, `set-cookie` 包括),供通过处理器使用.

## 移徙

带有迁移支持的 SQL 层 应用方案变化 `alchemy deploy` 通过内部炼金术:

-   运行 **仅在适用时** (从来没有在计划,从来没有在部署的运行时间—— 迁移代码从捆绑中去除),
-   仅在认证计划(插件、额外字段、索引)或目标数据库发生变化时重新运行,
-   应用缺失的表格、列和索引,通过 Better Auth 的映射器; 不安全的计划改变表面为 `BetterAuthMigrationError`。 。 。 .

一个直接的 **1.6 → 1.7.5+** 升级,核心账户计划不变:无 `issuer` 列或身份回填。 保持相同的认证秘密,并一起升级更好的Auth同步软件包. 微软标识器、遗留的OIDC/MCP客户端、SCIM以及设备代码可能需要人工制备; Alchemy不重写身份或转换插件数据. 见 [升级指南](https://alchemy.run/better-auth/upgrades/from-1-6-to-1-7) 在部署现有数据库之前.

选择退出 `migrate: false` 并管理自己的计划`npx auth@1.7.5 generate`) (中文(简体) ). 多个 `BetterAuth` 实例以一叠表示: 给每个不同的 `id` 将秘密+移民资源分解.

## 常见问题

### @alchemy\.run/better-auth 是什么？

为Alchemy更好的Auth集成\.

### 如何安装 @alchemy\.run/better-auth？

在项目目录运行 npm install @alchemy\.run/better-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（^4\.1\.0）、alchemy（2\.0\.0-beta\.85）、better-auth（^1\.7\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @alchemy\.run/better-auth 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alchemy\.run/better-auth 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alchemy\.run/better-auth 可以商用吗？

@alchemy\.run/better-auth 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @alchemy\.run/better-auth 的下载量有多少？

根据 npm 官方下载统计，@alchemy\.run/better-auth 在 2026/10/06 – 2026/11/04 这 30 天内被下载 135,215 次，日均约 4,507 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alchemy\.run/better-auth 还在维护吗？

最新版本 2\.0\.0-beta\.85 发布于 2026/11/03（3 天前）；至今共发布 90 个版本，其中过去 12 个月发布了 90 个；首次发布于 2026/04/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。