Expo 服务器

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

Server

GitHub

npm

更新日志

Bundled version:

~1.0.5

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 origin URL.

This typically returns the request's Origin header, which contains the request origin URL or defaults to null.

Returns:

string | null

A request origin

`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

`ImmutableRequest`

Server

Extends: _ImmutableRequest

An immutable version of the Fetch API's Request as received by middleware functions. 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

`MiddlewareFunction(request)`

Server

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

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

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