# @blitzjs/next 中文文档
规范地址：https://npmcn.com/package/%40blitzjs/next/
版本：3\.0\.2
npm 元数据更新时间：2025-09-11T13:04:04.558Z
中文译文更新时间：2026-11-08T06:58:44.142Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40blitzjs/next
原文对照：https://npmcn.com/package/%40blitzjs/next/?lang=original
项目主页：https://blitzjs.com/
源码仓库：https://github.com/blitz-js/blitz
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：111 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：blitz 3\.0\.2，next \*，react \*，tslog 4\.9\.0
- 首次发布：2021-04-05T20:38:30.114Z
- 最新版本发布：2025-09-11T13:04:04.337Z
- 近 30 天下载量：63162（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：311（近 12 个月 0 个）
## 中文简介
[](https://blitzjs.com/)
## 安装
```sh
npm install @blitzjs/next
```
也可以使用：`pnpm add @blitzjs/next`、`yarn add @blitzjs/next`、`bun add @blitzjs/next`
## README
[](https://blitzjs.com/)
[](https://discord.blitzjs.com/)[](https://npmcn.com/package/%40blitzjs/next/#readme-contributors-) [ ](https://github.com/blitz-js/blitz/blob/main/LICENSE)[](https://www.npmjs.com/package/@blitzjs/next)
# Next.js 的 Blitz 适应器
### [Blitzjs 网站( 网站)](https://blitzjs.com/)
### [GitHub 图像](https://github.com/blitz-js/blitz/tree/main/packages/blitz-next)
## 概览
这个 `@blitzjs/next` 适配器会显示特定的函数和组件 下一个.js框架.
## 设置
您可以安装 `@blitzjs/next` 运行以下命令:
```bash
npm i @blitzjs/next # yarn add @blitzjs/next # pnpm add @blitzjs/next
```
### 下一个配置
Blitz.js 扩展 `next.config.js` 通过接受一个 `blitz` 属性.
```ts
blitz?: {
resolverPath?: ResolverPathOptions;
customServer?: {
hotReload?: boolean;
};
};
```
关于设置“resolverPath”习惯的更多信息,请改为: \[RPC规格\] (/docs/rpc规格#url)
## 客户端
### 示例
内部 `src/blitz-client.ts`数字 :
```ts
import {setupBlitzClient} from "@blitzjs/next"
export const {withBlitz} = setupBlitzClient({
plugins: [],
})
```
然后进去 `src/pages/_app.tsx` 关闭 `MyApp` 函数与 `withBlitz` HOC组件.
```ts
import {ErrorFallbackProps, ErrorComponent, ErrorBoundary} from "@blitzjs/next"
import {AuthenticationError, AuthorizationError} from "blitz"
import type {AppProps} from "next/app"
import React, {Suspense} from "react"
import {withBlitz} from "src/blitz-client"
function RootErrorFallback({error}: ErrorFallbackProps) {
if (error instanceof AuthenticationError) {
return Error: You are not authenticated
} else if (error instanceof AuthorizationError) {
return (
)
} else {
return (
)
}
}
function MyApp({Component, pageProps}: AppProps) {
return (
)
}
export default withBlitz(MyApp)
```
提供者和组成部分是: 由\`闪电'/下\`提供
### API 密码
```ts
setupBlitzClient({
plugins: [],
})
```
#### 参数
- `plugins:` Blitz.js 插件阵列
- **需求**
#### 回返
带有 `withBlitz` HOC 包装器
## 服务器
### 示例
内部 `src/blitz-server.ts`
```ts
import {setupBlitzServer} from "@blitzjs/next"
export const {gSSP, gSP, api} = setupBlitzServer({
plugins: [],
})
```
### API 密码
```ts
setupBlitzServer({
plugins: [],
onError?: (err) => void
})
```
#### 参数
- `plugins:` Blitz.js 插件阵列
- **需求**
- `onError:` 抓取所有错误 _(服务如哨兵)_
#### 回返
带有 [`gSSP`](https://npmcn.com/package/%40blitzjs/next/#readme-blitzjs-next-gssp), (中文(简体) ), [`gSP`](https://npmcn.com/package/%40blitzjs/next/#readme-blitzjs-next-gsp) 打开 [`api`](https://npmcn.com/package/%40blitzjs/next/#readme-blitzjs-next-api) 包装.
### 自定义服务器
Blitz CLI 支持运行自定义 Next.js 服务器. 这意味着你可以 使用 Blitz.js CLI 来编译 javascript并打字 注入嵌入变量。 默认情况下, CLI 检查 `src/server/index.[ts | js]` 或者说 `src/server.[ts | js]`
关于自定义的更多信息 Next.js 服务器,请检查 [`official docs`](https://nextjs.org/docs/advanced-features/custom-server)
## 包装器
所有 Next.js 包装器功能都以 [`superjson`](https://github.com/blitz-js/superjson)。这意味着你可以 使用情况 `Date`, (中文(简体) ), `Map`, (中文(简体) ), `Set` 打开 `BigInt` 返回数据时。 还有一件事 注意: Blitz 在调用插件前先从插件中运行中间软件 下一个J请求处理器.
" gSSP " 、 " gSP " 和 " api " 的功能都从上下文传出 如果您正在使用认证插件, 则会话段 。 更多信息: 认证插件 此处\[@blitzjs/auth\] (/docs/auth).
### 实例
#### 获取StaticProps
```ts
import {gSP} from "src/blitz-server"
export const getStaticProps = gSP(async ({ctx}) => {
return {
props: {
data: {
userId: ctx?.session.userId,
session: {
id: ctx?.session.userId,
publicData: ctx?.session.$publicData,
},
},
},
}
})
```
#### 获取服务软件
```ts
import {gSSP} from "src/blitz-server"
export const getServerSideProps = gSSP(async ({ctx}) => {
return {
props: {
userId: ctx?.session.userId,
publicData: ctx?.session.$publicData,
},
}
})
```
#### api 密码
```ts
import {api} from "src/blitz-server"
export default api(async (req, res, ctx) => {
res.status(200).json({userId: ctx?.session.userId})
})
```
_有关 Next.js API 路线的更多信息,请访问他们的文件 [https://nextjs.org/docs/api-routes/introduction (英语)](https://nextjs.org/docs/api-routes/introduction)_
## 概念
### 在装入页面前认证用户
您可能想要检查用户是否在您的页面加载前登录 . 我们将会使用 `getCurrentUser` 内部查询 `getServerSideProps()` 直接调用查询。 然后你可以检查 如果用户在服务器上登录并使用内建的 Next.js 重定向属性 .
```ts
import {Routes, BlitzPage} from "@blitzjs/next"
import {gSSP} from "src/blitz-server"
import getCurrentUser from "src/users/queries/getCurrentUser"
export const getServerSideProps = gSSP(async ({ctx}) => {
const currentUser = await getCurrentUser(null, ctx)
if (currentUser) {
return {
props: {
user: currentUser,
},
}
} else {
return {
redirect: {
destination: Routes.LoginPage(),
permanent: false,
},
}
}
})
```
### 在服务器上获取数据时返回类型
您可以设定从 Next.js 数据获取函数返回的类型. Next.js 函数的所有 Blitz.js 包装器都接受通用。 一样 与 `BlitzPage` 类型.
例如,我们可以使用一些打字工具来帮助使用 返回类型 `getCurrentUser()`
```ts
import {Routes, BlitzPage} from "@blitzjs/next"
import {gSSP} from "src/blitz-server"
import getCurrentUser from "src/users/queries/getCurrentUser"
type TCurrentUser = Awaited>
export const getServerSideProps = gSSP<{user: TCurrentUser}>(async ({ctx}) => {
const currentUser = await getCurrentUser(null, ctx)
if (currentUser) {
return {
props: {
user: currentUser,
},
}
} else {
return {
redirect: {
destination: Routes.LoginPage(),
permanent: false,
},
}
}
})
const Page: BlitzPage<{user: TCurrentUser}> = ({user}) => {
return (
User Page
{user &&
{user.email}
}
)
}
export default Page
```
### 在初始页面装入时处理错误
有个边缘案例,你可能会在查询中出错,那就是 正在调用初始页面负载, 导致服务器错误而不是 击打 ``。这是因为初始装入时 该页面,直到 `_app.tsx` 实值 安装。 虽然,这是预期的行为,但还是有办法的.
例如,在找不到用户的查询中,您可以创建 `NotFoundError()` 然后返回状态代码.
```ts
export default resolver.pipe(resolver.zod(GetUser), async (input) => {
const {id} = input
const user = await db.user.findFirst({where: {id}})
if (!user) {
const userError = new NotFoundError("User not found")
return {
error: userError.statusCode,
}
} else {
return {
user,
}
}
})
```
然后在服务器上(在这种情况下) `getServerSideProps()`你可以打电话给 查询,如果在返回对象中找到错误键,则显示 错误.
```ts
export const getServerSideProps = gSSP(async ({ ctx }) => {
const user = await getUser({ 1 }, ctx)
if("error" in user) {
return { props: { error: user.error}}
} else {
return { props: { user }}
}
})
```
您也可以在服务器中捕捉错误 `_app.tsx` 并用 吐司组件.
```tsx
function MyApp({Component, pageProps}: AppProps) {
const getLayout = Component.getLayout || ((page) => page)
if (pageProps.error) {
return {pageProps.error.statusCode}
}
return (
{getLayout()}
)
}
```
## 常见问题
### 如何安装 @blitzjs/next？
在项目目录运行 npm install @blitzjs/next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：blitz（3\.0\.2）、next（\*）、react（\*）、tslog（4\.9\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @blitzjs/next 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @blitzjs/next 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @blitzjs/next 可以商用吗？
@blitzjs/next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @blitzjs/next 的下载量有多少？
根据 npm 官方下载统计，@blitzjs/next 在 2026/10/09 – 2026/11/07 这 30 天内被下载 63,162 次，日均约 2,105 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @blitzjs/next 还在维护吗？
最新版本 3\.0\.2 发布于 2025/09/11（1\.2 年前）；至今共发布 311 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/04/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。