# @emulators/adapter-next 中文文档

规范地址：https://npmcn.com/package/%40emulators/adapter-next/

版本：0\.13\.1
npm 元数据更新时间：2026-11-08T22:10:10.826Z
中文译文更新时间：2026-11-13T16:16:12.534Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40emulators/adapter-next
原文对照：https://npmcn.com/package/%40emulators/adapter-next/?lang=original
项目主页：https://emulate.dev/
源码仓库：https://github.com/vercel-labs/emulate

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

- 包体积（解压后）：24.2 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-02T17:37:41.397Z
- 最新版本发布：2026-11-08T22:10:10.484Z
- 近 30 天下载量：210965（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Next.js App路由器集成模拟. 在您的 Next.js app 中直接嵌入仿真器, 因此它们运行在相同的源头上, 解决了 Vercel 预览部署问题, OAuth 回调 URL 随每次部署而改变 .

## 安装

```sh
npm install @emulators/adapter-next
```

也可以使用：`pnpm add @emulators/adapter-next`、`yarn add @emulators/adapter-next`、`bun add @emulators/adapter-next`

## README

# @ 模拟器/ 适应器- next

Next.js App路由器集成模拟. 在您的 Next.js app 中直接嵌入仿真器, 因此它们运行在相同的源头上, 解决了 Vercel 预览部署问题, OAuth 回调 URL 随每次部署而改变 .

部分 [模拟](https://github.com/vercel-labs/emulate) ——为CI和无网络沙盒提供本地出入口替换服务.

## 安装

```bash
npm install @emulators/adapter-next
```

只安装适配器旁所需的模拟器 :

```bash
npm install @emulators/adapter-next @emulators/github @emulators/google
```

## 路由处理器

创建一个服务于模拟器流量的包罗万象的路径 :

```typescript
// app/emulate/[...path]/route.ts
import { createEmulateHandler } from '@emulators/adapter-next'
import * as github from '@emulators/github'
import * as google from '@emulators/google'

export const emulator = createEmulateHandler({
  services: {
    github: {
      emulator: github,
      seed: {
        users: [{ login: 'octocat', name: 'The Octocat' }],
        repos: [{ owner: 'octocat', name: 'hello-world', auto_init: true }],
      },
    },
    google: {
      emulator: google,
      seed: {
        users: [{ email: 'test@example.com', name: 'Test User' }],
      },
    },
  },
})

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = emulator
```

GitHub 图像 App 种子可能会省略 `private_key`。仅用处理器的服务器读取生成的密钥 `generatedSecrets()` 方法。 明文密钥不在此列;持续快照包含生成的密钥并需要一个带有原子的私人后端 `initialize`。 。 。 .

检查薄荷安装存储元数据 `/emulate/github/_emulate/installation-tokens`。 。 。 .

## Auth.js / 下一个 Auth 配置

将您的提供者指向同一来源的模拟路径 :

```typescript
import GitHub from 'next-auth/providers/github'

const baseUrl = process.env.VERCEL_URL
  ? `https://${process.env.VERCEL_URL}`
  : 'http://localhost:3000'

GitHub({
  clientId: 'any-value',
  clientSecret: 'any-value',
  authorization: { url: `${baseUrl}/emulate/github/login/oauth/authorize` },
  token: { url: `${baseUrl}/emulate/github/login/oauth/access_token` },
  userinfo: { url: `${baseUrl}/emulate/github/user` },
})
```

没有 `oauth_apps` 需要播种。 没有配置时, 模拟器跳过 `client_id`, (中文(简体) ), `client_secret`,以及 `redirect_uri` 审定.

## 无服务器的字体文件

模拟UI页面使用捆绑字体. 将您的 Next.js 配置包成无服务器跟踪 :

```typescript
// next.config.mjs
import { withEmulate } from '@emulators/adapter-next'

export default withEmulate({
  // your normal Next.js config
})
```

如果您在自定义路径上挂载全部, 请通过匹配的前缀 :

```typescript
export default withEmulate(nextConfig, { routePrefix: '/api/emulate' })
```

## 持久性

默认情况下,仿真器状态是内在的,并且在每个冷起步上重放. 要持续状态 整个重启,通过 `persistence` 适配器 :

```typescript
import { createEmulateHandler } from '@emulators/adapter-next'
import * as github from '@emulators/github'

const kvAdapter = {
  async load() { return await kv.get('emulate-state') },
  async save(data: string) { await kv.set('emulate-state', data) },
}

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateHandler({
  services: { github: { emulator: github } },
  persistence: kvAdapter,
})
```

为了地方发展, `@emulators/core` 船舶 `filePersistence`数字 :

```typescript
import { filePersistence } from '@emulators/core'

// ...
persistence: filePersistence('.emulate/state.json'),
```

## 链接

-   [完整文档](https://emulate.dev/)
-   [GitHub 图像](https://github.com/vercel-labs/emulate)

## 自定义仿真器

传递创建的定义 `defineEmulator` 从 `emulate` 改为 `services[name].emulator` 在框架适配器。 同一定义贯穿于国家综合指数和 `createEmulator({ service: definition, listen: false })` 在测试。 自定义条目接受可选的检查员和持久性适配器. 导出 `OPTIONS` 因此飞行前请求和自定义的选择路线到达了模拟器. root- relative directory stay 在服务挂载下,而自定义的 HTML 机构通过不变. 保持状态 在定义的国营工厂, 并等待操作员 `close()` 在测试。 见 [自定义仿真器指南](https://emulate.dev/docs/custom-emulators)。 。 。 .

## 常见问题

### @emulators/adapter-next 是什么？

Next\.js App路由器集成模拟\. 在您的 Next\.js app 中直接嵌入仿真器, 因此它们运行在相同的源头上, 解决了 Vercel 预览部署问题, OAuth 回调 URL 随每次部署而改变 \.

### 如何安装 @emulators/adapter-next？

在项目目录运行 npm install @emulators/adapter-next，或使用 pnpm add / yarn add / bun add。

### @emulators/adapter-next 支持 TypeScript 吗？

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

### @emulators/adapter-next 支持 ESM 还是 CommonJS？

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

### @emulators/adapter-next 可以商用吗？

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

### @emulators/adapter-next 的下载量有多少？

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

### @emulators/adapter-next 还在维护吗？

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