# @edge-csrf/nextjs 中文文档

规范地址：https://npmcn.com/package/%40edge-csrf/nextjs/

版本：2\.5\.3-cloudflare-rc1
npm 元数据更新时间：2025-05-08T10:29:38.734Z
中文译文更新时间：2026-11-13T06:33:33.466Z
软件包许可：MIT

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：21.4 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：next ^13\.0\.0 \|\| ^14\.0\.0 \|\| ^15\.0\.0
- 首次发布：2024-04-19T17:16:26.788Z
- 最新版本发布：2024-11-21T11:28:50.171Z
- 近 30 天下载量：187869（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 0 个）

## 中文简介

Edge-CSRF Next.js 集成库

## 安装

```sh
npm install @edge-csrf/nextjs
```

也可以使用：`pnpm add @edge-csrf/nextjs`、`yarn add @edge-csrf/nextjs`、`bun add @edge-csrf/nextjs`

## README

# 下一个.js

这是Edge-CSRF的"Next.js"集成的文件. 与Next.js 13、14和15的融合工作.

## 快速启动

首先,将整合库添加为您的应用程序的依赖性 :

```console
npm install @edge-csrf/nextjs
# or
pnpm add @edge-csrf/nextjs
# or
yarn add @edge-csrf/nextjs
```

下一个,创建中间软件文件(`middleware.ts`)用于您的项目并添加边缘-CSRF中间软件:

```typescript
// middleware.ts

import { createCsrfMiddleware } from '@edge-csrf/nextjs';

// initalize csrf protection middleware
const csrfMiddleware = createCsrfMiddleware({
  cookie: {
    secure: process.env.NODE_ENV === 'production',
  },
});

export const middleware = csrfMiddleware;
```

现在,所有HTTP提交请求(如POST,PUT,DELETE,PATCH)如果不包括一个有效的CSRF令牌,将被拒绝. 在表格中添加CSRF符号,您可以从表格中获取 `X-CSRF-Token` HTTP 响应头服务器侧或客户端侧. 例如:

### 应用路由器

```typescript
// app/page.tsx

import { headers } from 'next/headers';

export default async function Page() {
  const h = await headers();
  const csrfToken = h.get('X-CSRF-Token') || 'missing';

  return (
    <form action="/api/form-handler" method="post">
      <input type="hidden" value={csrfToken}>
      <input type="text" name="my-input">
      <input type="submit">
    </form>
  );
}
```

```typescript
// app/form-handler/route.ts

import { NextResponse } from 'next/server';

export async function POST() {
  return NextResponse.json({ status: 'success' });
}
```

### 页面路由器

```typescript
// pages/form.ts

import type { NextPage, GetServerSideProps } from 'next';
import React from 'react';

type Props = {
  csrfToken: string;
};

export const getServerSideProps: GetServerSideProps = async ({ res }) => {
  const csrfToken = res.getHeader('x-csrf-token') || 'missing';
  return { props: { csrfToken } };
}

const FormPage: NextPage<Props> = ({ csrfToken }) => {
  return (
    <form action="/api/form-handler" method="post">
      <input type="hidden" value={csrfToken}>
      <input type="text" name="my-input">
      <input type="submit">
    </form>
  );
}

export default FormPage;
```

```typescript
// pages/api/form-handler.ts

import type { NextApiRequest, NextApiResponse } from 'next';

type Data = {
  status: string
};

export default function handler(req: NextApiRequest, res: NextApiResponse<Data>) {
  // this code won't execute unless CSRF token passes validation
  res.status(200).json({ status: 'success' });
}
```

## 实例

这里有些 [实例](https://npmcn.com/package/%40edge-csrf/nextjs/examples) 在本寄存器中:

| 版本 | 路由器 | 执行情况 |
| --- | --- | --- |
| 下册.js 13 | 应用程序路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next13-approuter-html-submission) |
| 下册.js 13 | 应用程序路由器 | [JavaScript (动力学)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next13-approuter-js-submission-dynamic) |
| 下册.js 13 | 应用程序路由器 | [Java 脚本( 静态)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next13-approuter-js-submission-static) |
| 下册.js 13 | 页面路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next13-pagesrouter-html-submmission) |
| 下一个.js 14 | 应用程序路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-html-submission) |
| 下一个.js 14 | 应用程序路由器 | [JavaScript (动力学)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-js-submission-dynamic) |
| 下一个.js 14 | 应用程序路由器 | [Java 脚本( 静态)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-js-submission-static) |
| 下一个.js 14 | 应用程序路由器 | [哨兵](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-sentry) |
| 下一个.js 14 | 应用程序路由器 | [服务器动作( 窗体)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-server-action-form-submission) |
| 下一个.js 14 | 应用程序路由器 | [服务器动作( 非窗体)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-approuter-server-action-non-form-submission) |
| 下一个.js 14 | 页面路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next14-pagesrouter-html-submission) |
| 下一个.js 15 | 应用程序路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-html-submission) |
| 下一个.js 15 | 应用程序路由器 | [JavaScript (动力学)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-js-submission-dynamic) |
| 下一个.js 15 | 应用程序路由器 | [Java 脚本( 静态)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-js-submission-static) |
| 下一个.js 15 | 应用程序路由器 | [哨兵](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-sentry) |
| 下一个.js 15 | 应用程序路由器 | [服务器动作( 窗体)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-server-action-form-submission) |
| 下一个.js 15 | 应用程序路由器 | [服务器动作( 非窗体)](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-approuter-server-action-non-form-submission) |
| 下一个.js 15 | 页面路由器 | [HTML 窗体](https://npmcn.com/package/%40edge-csrf/nextjs/examples/next15-pagesrouter-html-submission) |

## 低级执行

如果您想要对响应进行较低级别的控制, 或者CSRF 保护会应用到哪个路线, 您可以使用 `createCsrfProtect()` 创建功能的方法,您可以在自定义的中间软件内使用:

```typescript
// middleware.ts

import { CsrfError, createCsrfProtect } from '@edge-csrf/nextjs';
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

// initalize csrf protection method
const csrfProtect = createCsrfProtect({
  cookie: {
    secure: process.env.NODE_ENV === 'production',
  },
});

// Next.js middleware function
export const middleware = async (request: NextRequest) => {
  const response = NextResponse.next();

  try {
    await csrfProtect(request, response);
  } catch (err) {
    if (err instanceof CsrfError) return new NextResponse('invalid csrf token', { status: 403 });
    throw err;
  }

  return response;
};
```

## 配置

```javascript
// default config

{
  cookie: {
    name: '_csrfSecret',
    path: '/',
    maxAge: undefined,
    domain: '',
    secure: true,
    httpOnly: true,
    sameSite: 'strict'
  },
  excludePathPrefixes: ['/_next/'],
  ignoreMethods: ['GET', 'HEAD', 'OPTIONS'],
  saltByteLength: 8,
  secretByteLength: 18,
  token: {
    fieldName: 'csrf_token',
    responseHeader: 'X-CSRF-Token',
    value: undefined
  }
}
```

## API 密码

下列出口品列于 `@edge-csrf/nextjs` 模块 :

### 类型

```
NextCsrfProtect - A function that implements CSRF protection for Next.js requests

  * @param {NextRequest} request - The Next.js request instance
  * @param {NextResponse} response - The Next.js response instance
  * @returns {Promise<void>} - The function completed successfully
  * @throws {CsrfError} - The function encountered a CSRF error
```

### 类

```
CsrfError - A class that inherits from Error and represents CSRF errors
```

### 方法

```
createCsrfMiddleware([, options]) - Create a new instance of Next.js middleware

  * @param {object} options - The configuration options
  * @returns {Middleware} - The middleware

createCsrfProtect([, options]) - Create a lower-level function that can be used inside Next.js middleware
                                 to implement CSRF protection for requests

  * @param {object} options - The configuration options
  * @returns {NextCsrfProtect} - The CSRF protection function
```

## 常见问题

### @edge-csrf/nextjs 是什么？

Edge-CSRF Next\.js 集成库注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @edge-csrf/nextjs？

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

### @edge-csrf/nextjs 支持 TypeScript 吗？

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

### @edge-csrf/nextjs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @edge-csrf/nextjs 可以商用吗？

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

### @edge-csrf/nextjs 的下载量有多少？

根据 npm 官方下载统计，@edge-csrf/nextjs 在 2026/10/13 – 2026/11/11 这 30 天内被下载 187,869 次，日均约 6,262 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @edge-csrf/nextjs 还在维护吗？

最新版本 2\.5\.3-cloudflare-rc1 发布于 2024/11/21（2 年前）；至今共发布 23 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/20。作者已将其标记为弃用，新项目建议寻找替代方案。