Expo 服务器

Expo Router 项目的服务端 API 和运行时。

Server

GitHub

npm

更新日志

Bundled version:

~55.0.0

expo-server 是面向 Expo Router 的服务端 API 和运行时库。它提供了一些辅助工具，可在你的 Expo Router API 路由或其他服务端代码中使用，并包含用于运行 Expo Router 服务端导出的适配器。

安装

Terminal

- npx expo install expo-server

要在项目中使用 expo-server，你需要将 Expo Router 项目配置为以 server 模式导出。请遵循 Expo Router 的 API Routes 指南中的说明：

API Routes

了解如何使用 Expo Router 创建服务器端点。

使用

expo-server 的运行时 API 只能在服务端代码中使用，并让你访问服务端运行时环境。运行时 API 暴露的函数可以在请求处理程序的异步上下文中调用，它们会为你提供当前请求的信息，或安排与传入请求并发执行的任务。

访问请求元数据

import { origin, environment } from 'expo-server';

export async function GET() {
  return Response.json({
    isProduction: environment() == null,
    isStaging: environment() === 'staging',
    origin: origin(),
  });
}

安排任务

import { runTask, deferTask } from 'expo-server';

export async function GET() {
  runTask(async () => {
    console.log('将立即运行。');
  });

  deferTask(async () => {
    console.log('将在响应解析后运行。');
  });

  return Response.json({ success: true });
}

适配器

expo-server 提供了适配器，用于在不同环境或不同云服务提供商的无服务器函数中运行 Expo Router 服务端导出。通常，每种运行时都需要各自的适配器才能与 expo-server 运行时配合使用。在部署到这些提供商之前，最好先熟悉 npx expo export 命令的基础知识。

适配器	提供商
`expo-server/adapter/bun`	Bun
`expo-server/adapter/express`	Express
`expo-server/adapter/http`	Node.js
`expo-server/adapter/netlify`	Netlify Functions
`expo-server/adapter/vercel`	Vercel Functions
`expo-server/adapter/workerd`	Cloudflare Workers

要了解如何在不同第三方服务上托管 API Routes，请遵循 Expo Router 的 API Routes 指南中的说明：

API Routes

了解如何在第三方服务上托管 API Routes。

按照约定，所有适配器都会导出一个接受参数对象的 createRequestHandler 函数。这个参数对象接受一个 build 参数，该参数必须设置为 npx expo export 创建的 dist/server 输出目录的相对路径。某些适配器还可能接受更多值来配置运行时 API。

import path from 'node:path';
import { createRequestHandler } from 'expo-server/adapter/http';

const onRequest = createRequestHandler({
  build: path.join(process.cwd(), 'dist/server'),
  environment: process.env.NODE_ENV,
});

API

Classes

`StatusError`

Server

Type: Class extends Error

An error response representation which can be thrown anywhere in server-side code.

A StatusError can be thrown by a request handler and will be caught by the expo-server runtime and replaced by a Response with the status and body that's been passed to the StatusError.

Example

import { StatusError } from 'expo-server';

export function GET(request, { postId }) {
  if (!postId) {
    throw new StatusError(400, 'postId parameter is required');
  }
}

StatusError Properties

`body`

Server

Type: string

`status`

Server

Type: number

Methods

`deferTask(fn)`

Server

Parameter	Type	Description
fn	`() => void \| Promise<unknown>`	A task function to execute after the request handler has finished.

Defers a task until after a response has been sent.

This only calls the task function once the request handler has finished resolving a Response and keeps the request handler alive until the task is completed. This is useful to run non-critical tasks after the request handler, for example to log analytics datapoints. If the request handler rejects with an error, deferred tasks won't be executed.

Returns:

void

`environment()`

Server

Returns the request's environment, if the server runtime supports this.

In EAS Hosting, the returned environment name is the alias or deployment identifier, but the value may differ for other providers.

Returns:

string | null

A request environment name, or null for production.

`origin()`

Server

Returns the current request's URL.

This typically returns the request's URL, or on certain platform, the origin of the request. This does not use the Origin header in development as it may contain an untrusted value.

Returns:

string | null

A request origin

`requestHeaders()`

Server

Returns an immutable copy of the current request's headers.

Returns:

ImmutableHeaders

`runTask(fn)`

Server

Parameter	Type	Description
fn	`() => Promise<unknown>`	A task function to execute. The request handler will be kept alive until this task finishes.

Runs a task immediately and instructs the runtime to complete the task.

A request handler may be terminated as soon as the client has finished the full Response and unhandled promise rejections may not be logged properly. To run tasks concurrently to a request handler and keep the request alive until the task is completed, pass a task function to runTask instead. The request handler will be kept alive until the task completes.

Returns:

void

`setResponseHeaders(updateHeaders)`

Server

Parameter	Type	Description
updateHeaders	`Headers \| Record<string, string \| string[]> \| (headers: Headers) => void \| Headers`	A `Headers` object, a record of headers, or a function that receives `Headers` to be updated or can return a `Headers` object that will be merged into the response headers.

Sets headers on the Response the current request handler will return.

This only updates the headers once the request handler has finished and resolved a Response. It will either receive a set of Headers or an equivalent object containing headers, which will be merged into the response's headers once it's returned.

Returns:

void

Interfaces

`ImmutableHeaders`

Server

Extends: _ImmutableHeaders

An immutable version of the Fetch API's Headers object. It cannot be mutated or modified.

`ImmutableRequest`

Server

Extends: _ImmutableRequest

An immutable version of the Fetch API's Request object. It cannot be mutated or modified, its headers are immutable, and you won't have access to the request body.

Property	Type	Description
method	`string`	The `method` read-only property of the `POST`, etc.) A String indicating the method of the request. MDN Reference
url	`string`	The `url` read-only property of the Request interface contains the URL of the request. MDN Reference

`MiddlewareMatcher`

Server

Middleware matcher settings that restricts the middleware to run conditionally.

Property	Type	Description
methods(optional)	`string[]`	Set this to a list of HTTP methods to conditionally run middleware on. By default, middleware will match all HTTP methods. Example `['POST', 'PUT', 'DELETE']`
patterns(optional)	`(string \| RegExp)[]`	Set this to a list of path patterns to conditionally run middleware on. This may be exact paths, paths containing parameter or catch-all segments (`'/posts/[postId]'` or `'/blog/[...slug]'`), or regular expressions matching paths. Example `['/api', '/posts/[id]', '/blog/[...slug]']`

`MiddlewareSettings`

Server

Exported from a +middleware.ts file to configure the server-side middleware function.

See: https://docs.expo.dev/router/reference/middleware/

Example

import type { MiddlewareSettings } from 'expo-server';

export const unstable_settings: MiddlewareSettings = {
  matcher: {
    methods: ['GET'],
    patterns: ['/api', '/admin/[...path]'],
  },
};

Property	Type	Description
matcher(optional)	`MiddlewareMatcher`	Matcher definition that restricts the middleware to run conditionally.

Types

`LoaderFunction(request, params)`

Server

Function type for route loaders. Loaders are executed on the server during SSR/SSG to fetch data required by a route.

During SSG (Static Site Generation), the request parameter will be undefined as there is no HTTP request at build time.

See: Data loaders for more information.

Example

import type { LoaderFunction } from 'expo-server';

export const loader: LoaderFunction = async (request, params) => {
  const data = await fetchData(params.id);
  return { data };
};

Parameter	Type	Description
request	`ImmutableRequest \| undefined`	An `ImmutableRequest` with read-only headers and no body access. In SSG, this is `undefined`
params	`Record<string, string \| string[]>`	Route parameters extracted from the URL path

Returns:

Promise<T> | T

`MiddlewareFunction(request)`

Server

Middleware function type. Middleware run for every request in your app, or on specified conditionally matched methods and path patterns, as per MiddlewareMatcher.

See: Server middleware for more information.

Example

import type { MiddlewareFunction } from 'expo-server';

const middleware: MiddlewareFunction = async (request) => {
  console.log(`Middleware executed for: ${request.url}`);
};

export default middleware;

Parameter	Type	Description
request	`ImmutableRequest`	An `ImmutableRequest` with read-only headers and no body access

Returns:

Promise<Response | void> | Response | void