Expo API 路由使用指南：何时使用与避免，文件结构与实战示例

expo-api-routes by expo/skills

12,600 周安装量

1,600 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/expo/skills --skill expo-api-routes

开发云服务

🇨🇳中文介绍

何时使用 API 路由

在以下情况时使用 API 路由：

服务器端密钥 — API 密钥、数据库凭据或绝不能到达客户端的令牌
数据库操作 — 不应暴露的直接数据库查询
第三方 API 代理 — 调用外部服务（OpenAI、Stripe 等）时隐藏 API 密钥
服务器端验证 — 在写入数据库之前验证数据
Webhook 端点 — 接收来自 Stripe 或 GitHub 等服务的回调
速率限制 — 在服务器级别控制访问
繁重计算 — 卸载在移动设备上处理缓慢的任务

何时不应使用 API 路由

在以下情况时避免使用 API 路由：

数据已公开 — 改为直接获取公共 API
无需密钥 — 静态数据或客户端安全的操作
需要实时更新 — 使用 WebSockets 或 Supabase Realtime 等服务
简单的 CRUD — 对于托管后端，考虑使用 Firebase、Supabase 或 Convex
文件上传 — 使用直传到存储的上传（S3 预签名 URL、Cloudflare R2）
仅身份验证 — 改用 Clerk、Auth0 或 Firebase Auth

文件结构

API 路由位于 app 目录中，带有 +api.ts 后缀：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

733,500 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

252,100 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

202,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

133,200 周安装

app/
  api/
    hello+api.ts          → GET /api/hello
    users+api.ts          → /api/users
    users/[id]+api.ts     → /api/users/:id
  (tabs)/
    index.tsx

// app/api/hello+api.ts
export function GET(request: Request) {
  return Response.json({ message: "Hello from Expo!" });
}

为每个 HTTP 方法导出命名函数：

// app/api/items+api.ts
export function GET(request: Request) {
  return Response.json({ items: [] });
}

export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ created: body }, { status: 201 });
}

export async function PUT(request: Request) {
  const body = await request.json();
  return Response.json({ updated: body });
}

export async function DELETE(request: Request) {
  return new Response(null, { status: 204 });
}

// app/api/users/[id]+api.ts
export function GET(request: Request, { id }: { id: string }) {
  return Response.json({ userId: id });
}

export function GET(request: Request) {
  const url = new URL(request.url);
  const page = url.searchParams.get("page") ?? "1";
  const limit = url.searchParams.get("limit") ?? "10";

  return Response.json({ page, limit });
}

export function GET(request: Request) {
  const auth = request.headers.get("Authorization");

  if (!auth) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

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

export async function POST(request: Request) {
  const { email, password } = await request.json();

  if (!email || !password) {
    return Response.json({ error: "Missing fields" }, { status: 400 });
  }

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

使用 process.env 处理服务器端密钥：

// app/api/ai+api.ts
export async function POST(request: Request) {
  const { prompt } = await request.json();

  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: "gpt-4",
      messages: [{ role: "user", content: prompt }],
    }),
  });

  const data = await response.json();
  return Response.json(data);
}

设置环境变量：

本地：创建 .env 文件（切勿提交）
EAS Hosting：使用 eas env:create 或 Expo 仪表板

为 Web 客户端添加 CORS：

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export function OPTIONS() {
  return new Response(null, { headers: corsHeaders });
}

export function GET() {
  return Response.json({ data: "value" }, { headers: corsHeaders });
}

export async function POST(request: Request) {
  try {
    const body = await request.json();
    // 处理...
    return Response.json({ success: true });
  } catch (error) {
    console.error("API error:", error);
    return Response.json({ error: "Internal server error" }, { status: 500 });
  }
}

启动包含 API 路由的开发服务器：

这将在 http://localhost:8081 启动一个本地服务器，并完全支持 API 路由。

使用 curl 测试：

curl http://localhost:8081/api/hello
curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'

部署到 EAS Hosting

npm install -g eas-cli
eas login

这将构建你的 API 路由并将其部署到 EAS Hosting（Cloudflare Workers）。

# 创建密钥
eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production

# 或使用 Expo 仪表板

在 eas.json 或 Expo 仪表板中配置。

EAS Hosting 运行时（Cloudflare Workers）

API 路由在 Cloudflare Workers 上运行。主要限制：

缺失/受限的 API

无 Node.js 文件系统 — fs 模块不可用
无原生 Node 模块 — 使用 Web API 或 polyfill
执行时间有限 — CPU 密集型任务有 30 秒超时限制
无持久连接 — WebSockets 需要 Durable Objects
fetch 可用 — 使用标准 fetch 进行 HTTP 请求

// 使用 Web Crypto 替代 Node crypto
const hash = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode("data")
);

// 使用 fetch 替代 node-fetch
const response = await fetch("https://api.example.com");

// 使用 Response/Request（已可用）
return new Response(JSON.stringify(data), {
  headers: { "Content-Type": "application/json" },
});

由于文件系统不可用，请使用云数据库：

Cloudflare D1 — 边缘 SQLite
Turso — 分布式 SQLite
PlanetScale — 无服务器 MySQL
Supabase — 带 REST API 的 Postgres
Neon — 无服务器 Postgres

// app/api/users+api.ts
import { createClient } from "@libsql/client/web";

const db = createClient({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

export async function GET() {
  const result = await db.execute("SELECT * FROM users");
  return Response.json(result.rows);
}

从客户端调用 API 路由

// 从 React Native 组件调用
const response = await fetch("/api/hello");
const data = await response.json();

// 带请求体
const response = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "John" }),
});

身份验证中间件

// utils/auth.ts
export async function requireAuth(request: Request) {
  const token = request.headers.get("Authorization")?.replace("Bearer ", "");

  if (!token) {
    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json" },
    });
  }

  // 验证令牌...
  return { userId: "123" };
}

// app/api/protected+api.ts
import { requireAuth } from "../../utils/auth";

export async function GET(request: Request) {
  const { userId } = await requireAuth(request);
  return Response.json({ userId });
}

// app/api/weather+api.ts
export async function GET(request: Request) {
  const url = new URL(request.url);
  const city = url.searchParams.get("city");

  const response = await fetch(
    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
  );

  return Response.json(await response.json());
}

绝不在客户端代码中暴露 API 密钥或机密信息
始终验证和清理用户输入
使用正确的 HTTP 状态码（200, 201, 400, 401, 404, 500）
使用 try/catch 优雅地处理错误
保持 API 路由专注 — 每个端点一个职责
使用 TypeScript 确保类型安全
在服务器端记录错误以便调试

2026 年 1 月 19 日

🇺🇸English

When to Use API Routes

Use API routes when you need:

Server-side secrets — API keys, database credentials, or tokens that must never reach the client
Database operations — Direct database queries that shouldn't be exposed
Third-party API proxies — Hide API keys when calling external services (OpenAI, Stripe, etc.)
Server-side validation — Validate data before database writes
Webhook endpoints — Receive callbacks from services like Stripe or GitHub
Rate limiting — Control access at the server level
Heavy computation — Offload processing that would be slow on mobile

When NOT to Use API Routes

Avoid API routes when:

Data is already public — Use direct fetch to public APIs instead
No secrets required — Static data or client-safe operations
Real-time updates needed — Use WebSockets or services like Supabase Realtime
Simple CRUD — Consider Firebase, Supabase, or Convex for managed backends
File uploads — Use direct-to-storage uploads (S3 presigned URLs, Cloudflare R2)
Authentication only — Use Clerk, Auth0, or Firebase Auth instead

File Structure

API routes live in the app directory with +api.ts suffix:

app/
  api/
    hello+api.ts          → GET /api/hello
    users+api.ts          → /api/users
    users/[id]+api.ts     → /api/users/:id
  (tabs)/
    index.tsx

Basic API Route

// app/api/hello+api.ts
export function GET(request: Request) {
  return Response.json({ message: "Hello from Expo!" });
}

HTTP Methods

Export named functions for each HTTP method:

// app/api/items+api.ts
export function GET(request: Request) {
  return Response.json({ items: [] });
}

export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ created: body }, { status: 201 });
}

export async function PUT(request: Request) {
  const body = await request.json();
  return Response.json({ updated: body });
}

export async function DELETE(request: Request) {
  return new Response(null, { status: 204 });
}

Dynamic Routes

// app/api/users/[id]+api.ts
export function GET(request: Request, { id }: { id: string }) {
  return Response.json({ userId: id });
}

Request Handling

Query Parameters

export function GET(request: Request) {
  const url = new URL(request.url);
  const page = url.searchParams.get("page") ?? "1";
  const limit = url.searchParams.get("limit") ?? "10";

  return Response.json({ page, limit });
}

Headers

export function GET(request: Request) {
  const auth = request.headers.get("Authorization");

  if (!auth) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

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

JSON Body

export async function POST(request: Request) {
  const { email, password } = await request.json();

  if (!email || !password) {
    return Response.json({ error: "Missing fields" }, { status: 400 });
  }

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

Environment Variables

Use process.env for server-side secrets:

// app/api/ai+api.ts
export async function POST(request: Request) {
  const { prompt } = await request.json();

  const response = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    },
    body: JSON.stringify({
      model: "gpt-4",
      messages: [{ role: "user", content: prompt }],
    }),
  });

  const data = await response.json();
  return Response.json(data);
}

Set environment variables:

Local : Create .env file (never commit)
EAS Hosting : Use eas env:create or Expo dashboard

CORS Headers

Add CORS for web clients:

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export function OPTIONS() {
  return new Response(null, { headers: corsHeaders });
}

export function GET() {
  return Response.json({ data: "value" }, { headers: corsHeaders });
}

Error Handling

export async function POST(request: Request) {
  try {
    const body = await request.json();
    // Process...
    return Response.json({ success: true });
  } catch (error) {
    console.error("API error:", error);
    return Response.json({ error: "Internal server error" }, { status: 500 });
  }
}

Testing Locally

Start the development server with API routes:

npx expo serve

This starts a local server at http://localhost:8081 with full API route support.

Test with curl:

curl http://localhost:8081/api/hello
curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'

Deployment to EAS Hosting

Prerequisites

npm install -g eas-cli
eas login

Deploy

eas deploy

This builds and deploys your API routes to EAS Hosting (Cloudflare Workers).

Environment Variables for Production

# Create a secret
eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production

# Or use the Expo dashboard

Custom Domain

Configure in eas.json or Expo dashboard.

EAS Hosting Runtime (Cloudflare Workers)

API routes run on Cloudflare Workers. Key limitations:

Missing/Limited APIs

No Node.js filesystem — fs module unavailable
No native Node modules — Use Web APIs or polyfills
Limited execution time — 30 second timeout for CPU-intensive tasks
No persistent connections — WebSockets require Durable Objects
fetch is available — Use standard fetch for HTTP requests

Use Web APIs Instead

// Use Web Crypto instead of Node crypto
const hash = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode("data")
);

// Use fetch instead of node-fetch
const response = await fetch("https://api.example.com");

// Use Response/Request (already available)
return new Response(JSON.stringify(data), {
  headers: { "Content-Type": "application/json" },
});

Database Options

Since filesystem is unavailable, use cloud databases:

Cloudflare D1 — SQLite at the edge
Turso — Distributed SQLite
PlanetScale — Serverless MySQL
Supabase — Postgres with REST API
Neon — Serverless Postgres

Example with Turso:

// app/api/users+api.ts
import { createClient } from "@libsql/client/web";

const db = createClient({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

export async function GET() {
  const result = await db.execute("SELECT * FROM users");
  return Response.json(result.rows);
}

Calling API Routes from Client

// From React Native components
const response = await fetch("/api/hello");
const data = await response.json();

// With body
const response = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "John" }),
});

Common Patterns

Authentication Middleware

// utils/auth.ts
export async function requireAuth(request: Request) {
  const token = request.headers.get("Authorization")?.replace("Bearer ", "");

  if (!token) {
    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json" },
    });
  }

  // Verify token...
  return { userId: "123" };
}

// app/api/protected+api.ts
import { requireAuth } from "../../utils/auth";

export async function GET(request: Request) {
  const { userId } = await requireAuth(request);
  return Response.json({ userId });
}

Proxy External API

// app/api/weather+api.ts
export async function GET(request: Request) {
  const url = new URL(request.url);
  const city = url.searchParams.get("city");

  const response = await fetch(
    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
  );

  return Response.json(await response.json());
}

Rules

NEVER expose API keys or secrets in client code
ALWAYS validate and sanitize user input
Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
Handle errors gracefully with try/catch
Keep API routes focused — one responsibility per endpoint
Use TypeScript for type safety
Log errors server-side for debugging

Weekly Installs

12.6K

Repository

expo/skills

GitHub Stars

1.6K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode8.9K

github-copilot8.7K

codex8.7K

gemini-cli8.6K

cursor8.2K

claude-code7.4K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Expo API 路由使用指南：何时使用与避免，文件结构与实战示例

🇨🇳中文介绍

何时使用 API 路由

何时不应使用 API 路由

文件结构

相关 Skills

基础 API 路由

HTTP 方法

动态路由

请求处理

查询参数

请求头

JSON 请求体

环境变量

CORS 请求头

错误处理

本地测试