# @crossmint/server-sdk 中文文档

规范地址：https://npmcn.com/package/%40crossmint/server-sdk/

版本：1\.2\.100
npm 元数据更新时间：2026-11-10T15:53:59.037Z
中文译文更新时间：2026-11-11T01:40:12.056Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40crossmint/server-sdk
原文对照：https://npmcn.com/package/%40crossmint/server-sdk/?lang=original
项目主页：https://github.com/Crossmint/crossmint-sdk#readme
源码仓库：https://github.com/Crossmint/crossmint-sdk

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

- 包体积（解压后）：71.5 kB，61 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-10-09T18:49:52.139Z
- 最新版本发布：2026-11-10T15:53:57.674Z
- 近 30 天下载量：3908（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：117（近 12 个月 52 个）

## 中文简介

这个SDK提供了一套工具,在使用服务器侧渲染(SSR)的Crossmint驱动应用程序中认证用户. 它简化了处理认证令牌和管理用户会话的程序,从而更容易整合正版

## 安装

```sh
npm install @crossmint/server-sdk
```

也可以使用：`pnpm add @crossmint/server-sdk`、`yarn add @crossmint/server-sdk`、`bun add @crossmint/server-sdk`

## README

# @ crossmint/ 服务器- sdk

这个SDK提供了一套工具,在使用服务器侧渲染(SSR)的Crossmint驱动应用程序中认证用户. 它简化了处理认证令牌和管理用户会话的过程,从而更容易将认证整合到您 Next.js 应用程序中.

## 安装

要安装 SDK, 您可以使用 npm 或 线 :

```bash
npm install @crossmint/server-sdk
```

## API 密钥和范围

使用服务器侧 API 密钥( S)`sk_...`) 从克罗斯明特控制台. 它需要什么样的范围取决于你所说的方法:

| 方法 | 范围 |
| --- | --- |
| `getSession`, (中文(简体) ), `handleCustomRefresh`, (中文(简体) ), `logout` | 无 |
| `getUser` | `users.read` |

`getSession` 使用 Crossmint 的公用密钥验证 JWT,并通过不检查瞄准镜的端点刷新会话. `getUser` 读取用户的配置文件,所以关键需要 `users.read`没有它, `getUser` 丢出一个 `CrossmintAuthenticationError` 与 `status` 403号.

## 使用量

要在您的应用程序中使用 SDK, 请遵循这些步骤 :

1.  导入 SDK 到您的工程中 :

```ts
import { createCrossmint, CrossmintAuth } from "@crossmint/server-sdk";

const crossmint = createCrossmint({
    apiKey: process.env.SERVER_CROSSMINT_API_KEY || "",
});

const crossmintAuth = CrossmintAuth.from(crossmint);
```

2.  使用 SDK 认证用户 :

通过请求对象,SDK读取会话 cookie for you. 这和Node.js有关 (单位:千美元)`IncomingMessage`)并获取 API(`Request`请求,包括Next.js中间软件和路由处理器:

```ts
const { jwt, userId } = await crossmintAuth.getSession(request);
```

客户端 SDK 将会话存储在 cookie 中, 范围为您的项目 : `crossmint-jwt-<projectId>` 财务报告和审定财务报表 `crossmint-refresh-token-<projectId>`,项目ID来自您的 API 密钥. `getSession(request)` 读取 这些名字,并读 遗产 `crossmint-jwt` 财务报告和审定财务报表 `crossmint-refresh-token` 名称仅当没有显示范围饼干时.

A Next.js 服务器组件中没有请求对象 。 按名字读取饼干 `getAuthCookieNames(projectId)` 返回并传递到 `getSession`。项目ID来自您的 API 密钥 :

```ts
import { cookies } from "next/headers";
import { getAuthCookieNames, validateAPIKey } from "@crossmint/server-sdk";

const apiKeyResult = validateAPIKey(process.env.SERVER_CROSSMINT_API_KEY ?? "");
if (!apiKeyResult.isValid) {
    throw new Error(apiKeyResult.message);
}

const cookieStore = await cookies();
const cookieNames = getAuthCookieNames(apiKeyResult.projectId);
const refreshToken = cookieStore.get(cookieNames.refreshToken)?.value;

if (refreshToken != null) {
    const { jwt, userId } = await crossmintAuth.getSession({
        jwt: cookieStore.get(cookieNames.jwt)?.value,
        refreshToken,
    });
}
```

3.  获取用户配置文件

`getSession` 返回用户的ID。 要获得他们的电子邮件,电话号码或链接到的X账户,将ID传递到 `getUser`它需要 `users.read` 选项

```ts
import { CrossmintAuthenticationError } from "@crossmint/server-sdk";

try {
    const user = await crossmintAuth.getUser(userId); // { id, email?, phoneNumber?, twitter? }
} catch (error) {
    if (error instanceof CrossmintAuthenticationError) {
        // error.status is 403 when the API key lacks users.read, 404 when the user has not signed in to this project
        console.error(error.status, error.message);
    }
    throw error;
}
```

4.  将认证材料存储在 cookie 中

如果您正在使用一个可访问响应对象的框架,可以通过将响应对象传递到 `getSession` 方法。 SDK 写有工程范围饼干名称( 日志也过期了未扫描的遗产 ) :

```ts
const { jwt, userId } = await crossmintAuth.getSession(request, response);
```

5.  注销

```ts
await crossmintAuth.logout(request);
```

## 警卫

SDK允许您设定 `httpOnly`, (中文(简体) ), `secure`, (中文(简体) ), `domain` 财务报告和审定财务报表 `sameSite` 用于饼干的选项。 这样可以控制饼干的存储和传输方式. 将它与自定义的刷新路由组合在一起,您可以将认证材料存储在HttpOnly Cookie中,这些认证材料被绑定在提供路由的域上.

在创建自定义刷新路由时配置 CrossmintAuth 这样做 :

```ts
const crossmintAuth = CrossmintAuth.from(crossmint, {
    cookieOptions: {
        httpOnly: true,
        sameSite: "Strict",
        secure: true,
        domain: ".example.com",
    },
});
```

`httpOnly` 仅适用于刷新符号。 会话符号不会是 Http Only ,因为它在客户端中用于API 调用 .

## 设置自定义刷新路由

要设置自定义刷新路由, 您可以使用 `handleCustomRefresh` 方法。 这种方法会刷新符号并还原新的认证材料. 这样,认证材料可以被存储在被绑定在所提供路由域的饼干中.

在使用获取 API 的环境中 `Request` 财务报告和审定财务报表 `Response` 对象, `handleCustomRefresh` 返回响应对象 :

```ts
return await crossmintAuth.handleCustomRefresh(request);
```

在使用Node.js API的环境中,您还需要提供响应对象并结束响应:

```ts
await crossmintAuth.handleCustomRefresh(req, res);
res.end();
```

### 使用自定义刷新路由

您也可以提供自定义刷新路由 :

```typescript
const crossmintAuth = CrossmintAuth.from(crossmint, {
    refreshRoute: `${process.env.APP_URL || "http://localhost:3000"}/api/refresh`,
});
```

SDK将使用提供的路由,而不是Crossmint的刷新终点. 在服务器上, 将它配置为静态的、可信任的绝对 URL; 永远不要从收到的请求或请求中得出它 `Host` 头曰. 在生产中使用HTTPS. 服务器 SDK 验证刷新 JWT 的签名,过期,以及针对 Crossmint 的 JWKS 的项目受众,并从已验证的用户ID取出 `sub` 索赔.

## 设置自定义登录路径

使用时 `HttpOnly` cookie,登录不能发生客户端,因为它不能访问cookie. 可以设置自定义的登录路由来处理登录过程.

在使用获取 API 的环境中, `logout` 返回响应对象 :

```ts
return await crossmintAuth.logout(request);
```

在使用Node.js API的环境中,您还需要提供响应对象并结束响应:

```ts
await crossmintAuth.logout(req, res);
res.end();
```

## 常见问题

### @crossmint/server-sdk 是什么？

这个SDK提供了一套工具,在使用服务器侧渲染\(SSR\)的Crossmint驱动应用程序中认证用户\. 它简化了处理认证令牌和管理用户会话的程序,从而更容易整合正版

### 如何安装 @crossmint/server-sdk？

在项目目录运行 npm install @crossmint/server-sdk，或使用 pnpm add / yarn add / bun add。

### @crossmint/server-sdk 支持 TypeScript 吗？

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

### @crossmint/server-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossmint/server-sdk 可以商用吗？

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

### @crossmint/server-sdk 的下载量有多少？

根据 npm 官方下载统计，@crossmint/server-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,908 次，日均约 130 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crossmint/server-sdk 还在维护吗？

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