# @faapi/next 中文文档

规范地址：https://npmcn.com/package/%40faapi/next/

版本：7\.21\.0
npm 元数据更新时间：2026-10-31T23:21:33.536Z
中文译文更新时间：2026-11-01T03:11:51.744Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40faapi/next
原文对照：https://npmcn.com/package/%40faapi/next/?lang=original
项目主页：https://github.com/faapi/faapi#readme
源码仓库：https://github.com/faapi/faapi

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

- 包体积（解压后）：47.3 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：next \>=13\.0\.0，@faapi/faapi ^7\.21\.0
- 首次发布：2026-06-29T17:24:50.959Z
- 最新版本发布：2026-10-31T23:21:32.697Z
- 已发布版本数：142（近 12 个月 142 个）

## 中文简介

faapi的Next.js集成-从单个服务器上提供faapi api和Next.js页面

## 安装

```sh
npm install @faapi/next
```

也可以使用：`pnpm add @faapi/next`、`yarn add @faapi/next`、`bun add @faapi/next`

## README

# @faapi/next

> Next.js + faapi 单进程单端口集成

`@faapi/next` 让 faapi 和 Next.js 运行在同一个进程中，共享同一个端口。`/api/*` 路径走 faapi，其余路径走 Next.js，无需写 custom server 代码。

## 安装

```bash
pnpm add @faapi/next next
# 或
npm install @faapi/next next
```

要求 Node.js >= 24，Next.js >= 13。

## 快速开始

在 `faapi.config.ts` 中声明插件：

```ts
export default {
  plugins: ['@faapi/next'],
} satisfies FaapiConfig;
```

然后像普通 faapi 项目一样启动：

```bash
npx faapi
```

`/api/*` 的请求由 faapi handler 处理，其余请求（页面、静态资源、HMR）由 Next.js 处理。

### 自定义 API 前缀

```ts
export default {
  plugins: [
    ['@faapi/next', { apiPrefix: '/v1' }],
  ],
} satisfies FaapiConfig;
```

### 生产模式

```bash
npx faapi build
node dist/main
```

## HTTP 分流

| 请求路径 | 处理方 |
| --- | --- |
| `/api/user` | faapi handler |
| `/api/hello?name=world` | faapi handler |
| `/` | Next.js 首页 |
| `/about` | Next.js 页面 |
| `/api2`（不匹配 /api 前缀） | Next.js |
| `/_next/*`（HMR / 静态资源） | Next.js |

## WebSocket 分流

| upgrade 请求 | 处理方 |
| --- | --- |
| `/api/chat`（faapi WS 路由） | faapi WebSocket handler |
| `/_next/webpack-hmr` | Next.js HMR |

## 浏览器端请求层（`@faapi/next/client`）

客户端组件（`'use client'`）的 API 请求统一走 `apiCall`，它封装了 fetch + faapi 信封（`{ data }` / `{ error }`）解包，失败一律抛结构化 `ApiError`（携带 `code` / `status` / `message`，`VALIDATION_ERROR` 时附 `issues`）：

```tsx
'use client';
import { apiCall, ApiError } from '@faapi/next/client';

async function submit() {
  try {
    const user = await apiCall<{ id: number }>('/api/user', { method: 'POST' });
    toast.success('已保存');
  } catch (e) {
    toast.error(e instanceof Error ? e.message : String(e)); // message 恒为可读文案
  }
}
```

### 为什么需要 apiCall

`/api/*` 的错误响应恒为 JSON 信封，但链路其他层会返回 HTML（反代/网关错误页、Next.js 404 页、SSO 登录守卫的 302 重定向）。直接 `res.json()` 会把裸 `Unexpected token '<'` SyntaxError 原文抛上界面。`apiCall` 把这些异常响应转译为可行动的中文提示（502/503 → 服务暂时不可用、504 → 服务响应超时、401 → 登录已过期、登录页重定向 → 登录状态已失效），排障现场（状态码 / URL / body 前 200 字符）留在 `console.error`。`statusMessage` 一并导出，可 fork 自定义文案。

### ⚠️ 必须用 `@faapi/next/client` 子路径导入

主入口 `@faapi/next` 是**服务端插件**（依赖 `@faapi/faapi` 与 next 服务端模块）。客户端组件若误用主入口，会把 `node:fs` / `node:child_process` 等服务端代码拉进浏览器 bundle，导致 Next.js build 失败。客户端代码只从 `@faapi/next/client` 导入；`./client` 入口零 Node 依赖，可安全进入客户端 bundle。

### 已知限制

`apiCall` 按主包 `config.response` 的**默认信封**解包。若你在 `faapi.config.ts` 自定义了 `response.ok` / `response.fail`，请自行包装 apiCall（替换解包段），不要两处各改各的。

## 许可证

[MIT](https://github.com/faapi/faapi/blob/main/LICENSE)

## 常见问题

### @faapi/next 是什么？

faapi的Next\.js集成-从单个服务器上提供faapi api和Next\.js页面

### 如何安装 @faapi/next？

在项目目录运行 npm install @faapi/next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@faapi/faapi（^7\.21\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @faapi/next 支持 TypeScript 吗？

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

### @faapi/next 支持 ESM 还是 CommonJS？

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

### @faapi/next 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @faapi/next 可以商用吗？

@faapi/next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @faapi/next 还在维护吗？

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