nuxt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nuxt Integration

Nuxt集成

The

@emulators/adapter-nuxt

package embeds emulators directly into a Nuxt app, running them on the same origin. This is useful for preview deployments where OAuth callback URLs change with every deployment.

@emulators/adapter-nuxt

包可将模拟器直接嵌入Nuxt应用中，使其在同源环境下运行。这对于预览部署非常有用，因为此类部署的OAuth回调URL会随每次部署而变化。

Install

安装

bash

npm install @emulators/adapter-nuxt @emulators/github @emulators/google

Only install the emulators you need. Each

@emulators/*

package is published independently, keeping server bundles small.

bash

npm install @emulators/adapter-nuxt @emulators/github @emulators/google

仅安装你需要的模拟器。每个

@emulators/*

包都是独立发布的，可保持服务器包体积小巧。

Server Route

服务器路由

Create a named catch-all route that serves emulator traffic:

typescript

// server/routes/emulate/[...path].ts
import { createEmulateHandler } from '@emulators/adapter-nuxt'
import * as github from '@emulators/github'
import * as google from '@emulators/google'

export default defineEventHandler(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' }],
      },
    },
  },
}))

This creates these routes:

```
/emulate/github/**
```
serves the GitHub emulator
```
/emulate/google/**
```
serves the Google emulator

创建一个命名兜底路由来处理模拟器流量：

typescript

// server/routes/emulate/[...path].ts
import { createEmulateHandler } from '@emulators/adapter-nuxt'
import * as github from '@emulators/github'
import * as google from '@emulators/google'

export default defineEventHandler(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' }],
      },
    },
  },
}))

这会创建以下路由：

```
/emulate/github/**
```
提供GitHub模拟器服务
```
/emulate/google/**
```
提供Google模拟器服务

Nuxt Config

Nuxt配置

Emulator UI pages use bundled fonts. Wrap your Nuxt config so Nitro traces the core package assets into production builds:

typescript

// nuxt.config.ts
import { withEmulate } from '@emulators/adapter-nuxt'

export default defineNuxtConfig(withEmulate({
  // your normal Nuxt config
}))

模拟器UI页面使用打包后的字体。包装你的Nuxt配置，让Nitro将核心包资源追踪到生产构建中：

typescript

// nuxt.config.ts
import { withEmulate } from '@emulators/adapter-nuxt'

export default defineNuxtConfig(withEmulate({
  // 你的常规Nuxt配置
}))

OAuth Configuration

OAuth配置

Point your OAuth provider at the emulator paths on the same origin:

typescript

const baseUrl = process.env.NUXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'

export const githubOAuth = {
  clientId: 'any-value',
  clientSecret: 'any-value',
  authorizationUrl: `${baseUrl}/emulate/github/login/oauth/authorize`,
  tokenUrl: `${baseUrl}/emulate/github/login/oauth/access_token`,
  userInfoUrl: `${baseUrl}/emulate/github/user`,
}

oauth_apps

need to be seeded. When none are configured, the emulator skips

client_id

client_secret

, and

redirect_uri

validation.

将你的OAuth提供商指向同源的模拟器路径：

typescript

const baseUrl = process.env.NUXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'

export const githubOAuth = {
  clientId: 'any-value',
  clientSecret: 'any-value',
  authorizationUrl: `${baseUrl}/emulate/github/login/oauth/authorize`,
  tokenUrl: `${baseUrl}/emulate/github/login/oauth/access_token`,
  userInfoUrl: `${baseUrl}/emulate/github/user`,
}

无需预种子

oauth_apps

。当未配置任何

oauth_apps

时，模拟器会跳过

client_id

、

client_secret

和

redirect_uri

的验证。

Persistence

持久化

By default, emulator state is in-memory and resets on every cold start. To persist state across restarts, pass a

persistence

adapter.

默认情况下，模拟器状态存储在内存中，每次冷启动时都会重置。要在重启后保留状态，请传入一个

persistence

适配器。

Nitro Storage

Nitro存储

typescript

import { createEmulateHandler } from '@emulators/adapter-nuxt'
import * as github from '@emulators/github'

const storageAdapter = {
  async load() { return await useStorage('emulate').getItem<string>('state') },
  async save(data: string) { await useStorage('emulate').setItem('state', data) },
}

export default defineEventHandler(createEmulateHandler({
  services: { github: { emulator: github } },
  persistence: storageAdapter,
}))

typescript

import { createEmulateHandler } from '@emulators/adapter-nuxt'
import * as github from '@emulators/github'

const storageAdapter = {
  async load() { return await useStorage('emulate').getItem<string>('state') },
  async save(data: string) { await useStorage('emulate').setItem('state', data) },
}

export default defineEventHandler(createEmulateHandler({
  services: { github: { emulator: github } },
  persistence: storageAdapter,
}))

File Persistence

文件持久化

For local development,

@emulators/core

ships a file-based adapter:

typescript

import { filePersistence } from '@emulators/core'

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

对于本地开发，

@emulators/core

提供了一个基于文件的适配器：

typescript

import { filePersistence } from '@emulators/core'

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

How Persistence Works

持久化工作原理

Cold start: The adapter loads state from the persistence adapter. If found, it restores the full Store and token map. If not found, it seeds from config and saves the initial state.
After mutating requests (POST, PUT, PATCH, DELETE): State is saved. Saves are serialized via an internal queue to prevent race conditions.
No persistence configured: Falls back to pure in-memory. Seed data re-initializes on every cold start.

冷启动：适配器从持久化加载状态。如果找到状态，则恢复完整的Store和令牌映射；如果未找到，则从配置预种子数据并保存初始状态。
变更请求后（POST、PUT、PATCH、DELETE）：状态会被保存。保存操作通过内部队列序列化，以防止竞态条件。
未配置持久化：回退到纯内存模式。预种子数据会在每次冷启动时重新初始化。

How It Works

工作原理

Incoming request:

/emulate/github/login/oauth/authorize?client_id=...

Parse: service =
```
github
```
, rest =
```
/login/oauth/authorize
```
Strip prefix: A new
```
Request
```
is created with the stripped path and forwarded to the GitHub service app
Rewrite response: HTML
```
action
```
and
```
href
```
attributes, CSS
```
url()
```
font references, and
```
Location
```
headers get the service prefix prepended
Persist: After mutating requests, state is saved via the persistence adapter

传入请求：

/emulate/github/login/oauth/authorize?client_id=...

解析：服务 =
```
github
```
，剩余路径 =
```
/login/oauth/authorize
```
移除前缀：创建一个新的
```
Request
```
，移除前缀后转发给GitHub服务应用
重写响应：HTML的
```
action
```
和
```
href
```
属性、CSS的
```
url()
```
字体引用以及
```
Location
```
头都会被添加服务前缀
持久化：变更请求完成后，状态通过持久化适配器保存

Limitations

局限性

Requires a Node-compatible Nuxt server runtime since emulators use Node APIs
Concurrent serverless instances writing to the same persistence adapter use last write wins semantics, which is acceptable for dev and preview traffic

需要兼容Node的Nuxt服务器运行时，因为模拟器使用Node API
写入同一持久化适配器的并发无服务器实例采用“最后写入获胜”的语义，这对于开发和预览流量是可接受的

Config Reference

配置参考

createEmulateHandler(config, options?)

createEmulateHandler(config, options?)

Field	Type	Description
`services`	`Record<string, EmulatorEntry>`	Map of service name to emulator config
`persistence?`	`PersistenceAdapter`	Optional persistence adapter for state across cold starts

Each

EmulatorEntry

Field	Type	Description
`emulator`	`EmulatorModule`	The emulator package, such as `import * as github from '@emulators/github'`
`seed?`	`Record<string, unknown>`	Seed data matching the service's config schema

Options:

Option	Type	Default	Description
`param`	`string`	`"path"`	Named catch-all route param
`routePrefix`	`string`	detected	Path prefix where the catch-all route is mounted

字段	类型	描述
`services`	`Record<string, EmulatorEntry>`	服务名称到模拟器配置的映射
`persistence?`	`PersistenceAdapter`	可选的持久化适配器，用于跨冷启动保留状态

每个

EmulatorEntry

：

字段	类型	描述
`emulator`	`EmulatorModule`	模拟器包，例如 `import * as github from '@emulators/github'`
`seed?`	`Record<string, unknown>`	匹配服务配置 schema 的预种子数据

选项：

选项	类型	默认值	描述
`param`	`string`	`"path"`	命名兜底路由参数
`routePrefix`	`string`	自动检测	兜底路由挂载的路径前缀

withEmulate(nuxtConfig)

withEmulate(nuxtConfig)

Wraps a Nuxt config to include

@emulators/core

assets in Nitro's production trace. Call it inside

defineNuxtConfig

nuxt.config.ts

包装Nuxt配置，将

@emulators/core

资源纳入Nitro的生产构建追踪。在

nuxt.config.ts

的

defineNuxtConfig

中调用此方法。

PersistenceAdapter

PersistenceAdapter

typescript

interface PersistenceAdapter {
  load(): Promise<string | null>
  save(data: string): Promise<void>
}

typescript

interface PersistenceAdapter {
  load(): Promise<string | null>
  save(data: string): Promise<void>
}

nuxt

Original

Translation

Nuxt Integration

Nuxt集成

Install

安装

Server Route

服务器路由

Nuxt Config

Nuxt配置

OAuth Configuration

OAuth配置

Persistence

持久化

Nitro Storage

Nitro存储

File Persistence

文件持久化

How Persistence Works

持久化工作原理

How It Works

工作原理

Limitations

局限性

Config Reference

配置参考

`createEmulateHandler(config, options?)`

`createEmulateHandler(config, options?)`

`withEmulate(nuxtConfig)`

`withEmulate(nuxtConfig)`

`PersistenceAdapter`

`PersistenceAdapter`