# @appwarden/middleware 中文文档

规范地址：https://npmcn.com/package/%40appwarden/middleware/

版本：3\.17\.14
npm 元数据更新时间：2026-10-29T23:33:01.296Z
中文译文更新时间：2026-11-07T03:47:37.266Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：355 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14\.0
- 运行依赖：4 个
- peer 依赖：next \>=14，astro \>=4\.0\.0，@tanstack/start ^1\.120\.20，@vercel/functions \>=1\.0\.0，@astrojs/cloudflare \>=11\.0\.0，@opennextjs/cloudflare \>=1\.16\.6
- 首次发布：2024-09-10T23:14:12.964Z
- 最新版本发布：2026-10-29T23:33:00.970Z
- 近 30 天下载量：2060（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：97（近 12 个月 73 个）

## 中文简介

立即禁用 Cloudflare 或 Vercel 上部署的应用程序中的所有用户交互

## 安装

```sh
npm install @appwarden/middleware
```

也可以使用：`pnpm add @appwarden/middleware`、`yarn add @appwarden/middleware`、`bun add @appwarden/middleware`

## README

# @ appwarden/ 中间软件

[![Docs](https://img.shields.io/badge/Documentation-blue)](https://appwarden.io/docs/reference/appwarden-middleware) [![GitHub](https://img.shields.io/badge/GitHub-appwarden%2Fmiddleware-181717?logo=github&logoColor=white)](https://github.com/appwarden/middleware) [![npm version](https://img.shields.io/npm/v/@appwarden/middleware.svg)](https://www.npmjs.com/package/@appwarden/middleware) [![npm provenance](https://img.shields.io/badge/npm-provenance-green)](https://docs.npmjs.com/generating-provenance-statements) ![Test Coverage](https://img.shields.io/badge/coverage-93.03%25-brightgreen) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 核心特征

-   **分解整合**:通过Discord命令对您的网站进行检疫(`/quarantine [un]lock`(中文(简体) )
-   **即时隔离**: 启动时立即将所有访问者重定向到一个锁定页面,以阻止进行中的攻击.
-   **非基于内容安全政策(见 [特性相容性](https://npmcn.com/package/%40appwarden/middleware/#readme-feature-compatibility)(中文(简体) )**: 在所支持的 Cloudflare 上使用 HTML 重写方式, 部署基于非ce的内容安全政策.
-   **最小运行时间**: 通过使用可忽略的性能影响 `event.waitUntil` 状态检查

### 特性相容性

下表概述了每个平台上有哪些Appwarden功能,包括检疫执行和内容安全政策(CSP)支持(有或没有非ces).

| 平台/适应器 | 软件包/ 切入点 | 检疫 | 社区支助方案 | CSP 农斯 |
| --- | --- | --- | --- | --- |
| Cloudflare — 通用中间软件 | `@appwarden/middleware/cloudflare` | ✅ | ✅ | ✅ |
| 云花相会-Astro | `@appwarden/middleware/cloudflare/astro` | ✅ | ✅ | ✅ |
| Cloudflare - 反应路由器 | `@appwarden/middleware/cloudflare/react-router` | ✅ | ✅ | ✅ |
| Cloudflare – TanStack 开始 | `@appwarden/middleware/cloudflare/tanstack-start` | ✅ | ✅ | ✅ |
| Cloudflare – Next.js(打开下一个适配器) | `@appwarden/middleware/cloudflare/nextjs` | ✅ | ✅ | ❌ |
| Vercel - 通用中间软件 | `@appwarden/middleware/vercel` | ✅ | ✅ | ❌ |

基于nonce的CSP需要HTML重写,并且只能在Cloudflare上提供. Next.js on Cloudflare (OpenNext) 和Vercel Edge Middleware 仅应用 CSP 头并做 **没有** 支持非切数。 如果您在 Cloudflare 上使用 Next.js, 请使用 Cloudflare 通用中件支持 CSP 非ce .

## 配置

以下选项通过 Cloudflare 和 Vercel 中间软件包共享 。 你必须 至少提供其中之一 `website`, (中文(简体) ), `api`,或 `multidomainConfig` (只有云雾通用) Appwarden知道哪些要求保护.

### `appwardenApiToken` (必须)

Appwarden API 令牌用于认证向 Appwarden API 提出的请求. 见 [API 令牌管理指南](https://appwarden.io/docs/guides/api-token-management) 关于创建和 管理你的纪念品.

将此令牌视为一个秘密( 类似于密码): 不要将其承诺用于源控件和存储 在环境变量或秘密管理中进行。 使用 Appwarden 存储 API 令牌 AES-GCM加密,在创建后不显示.

### `debug` (可选)

默认为 `false`设置为 `true` (或字符串) `"true"`在初始设置中进行日志锁检查 和配置问题。 集成稳定后即停产.

### `appwardenApiHostname` (可选)

预留用于内部测试. 保留未设置用于生产 Appwarden API .

### `bypassPaths` (可选)

一连串的路径模式,应该总是通过而不检查锁. 模式匹配 精确的路径和分界线的子路径。 尾声 `/*` 是可选的.

```ts
bypassPaths: ["/health", "/api/health"]
```

### `website` (可选)

配置网站隔离和CSP.

-   `lockPageSlug` – 站点被锁定时的相对路径重定向. 默认为 `/maintenance`。 。 。 .
    
-   `cspMode` - 可选 CSP 模式 : `"disabled"`, (中文(简体) ), `"report-only"`,或 `"enforced"`。省略时,无 CSP 头被应用.
    
-   `cspDirectives` - 可选的 CSP 指令对象,或 JSON 字符串. 例如:
    
    ```ts
    website: {
      lockPageSlug: "/maintenance",
      cspMode: "enforced",
      cspDirectives: {
        "script-src": ["'self'", "{{nonce}}"],
        "style-src": ["'self'", "{{nonce}}"],
      },
    }
    ```
    

在指令中添加非ce(参见 [特性相容性](https://npmcn.com/package/%40appwarden/middleware/#readme-feature-compatibility)页:1 `"{{nonce}}"` 源列表中的占位符.

### `api` (可选)

配置API隔离.

-   `basePaths` – 一系列路径图案,可视为API路径. 默认为 `["/"]`。 。 。 .
-   `response` - 当 API 路由锁定时返回的可选响应 :
    -   `status` - 默认为 `503`
    -   `body` - 默认为 `{"error":"Service unavailable"}`
    -   `headers` - 可选数组 `{ name, value }`

```ts
api: {
  basePaths: ["/api"],
  response: {
    status: 503,
    body: '{"error":"Service unavailable"}',
    headers: [{ name: "Content-Type", value: "application/json" }],
  },
}
```

### `multidomainConfig` (只有云彩通用,可选)

每个主机名覆盖。 每个键是主机名, 每个值可以覆盖 `website`, (中文(简体) ), `api`, (中文(简体) ), `bypassPaths`,以及 `debug`。域特有值优先于顶级值.

```ts
multidomainConfig: {
  "app.example.com": {
    website: { lockPageSlug: "/maintenance-app" },
  },
  "api.example.com": {
    api: { basePaths: ["/api"] },
  },
}
```

### `cacheUrl` (仅限Vercel)

缓存提供者的 URL 或连接字符串( 例如 Upstash 或 Vercel Edge Cfig) 将隔离状态保存在您的域。 见 [Vercel 集成指南](https://appwarden.io/docs/guides/vercel-middleware-integration#3-configure-a-cache-provider) 用于缓存提供者配置细节.

### `vercelApiToken` (仅限Vercel)

Appwarden 用来管理 Vercel Edge Config 缓存提供者的 Vercel API 令牌, 以同步您的域的隔离状态 . 见 [Vercel 集成指南](https://appwarden.io/docs/guides/vercel-middleware-integration#3-configure-a-cache-provider) 用于缓存提供者配置细节.

Appwarden从未存储或登录您的 Vercel API 令牌; 它仅用于管理您的域的隔离状态缓存 .

## 安装

与网站兼容 [云雾花](https://developers.cloudflare.com/workers/static-assets/) 或者说 [维塞尔](https://vercel.com/)。 。 。 .

更多背景和高级配置请见 [应用文档](https://appwarden.io/docs)。 。 。 .

### 1\. 云层

#### 1.1 通用中件(云花板工人直接使用)

这个 **通用中间软件** (单位:千美元)`@appwarden/middleware/cloudflare`支持Cloudflare上部署的任何网站。 它作为独立的云旗工人部署,并产生额外的使用费。 使用这个通用中间器件最简单的方法是通过我们 [建立- 云层- 行动](https://github.com/appwarden/build-cloudflare-action); 见 [云花板整合指南](https://appwarden.io/docs/guides/cloudflare-middleware-integration#1-set-up-the-github-actions-workflow) 用于工作流程细节。 如果您更愿意管理自己的Cloudflare Worker, 而不是使用 GitHub 动作, 您可以直接使用 `@appwarden/middleware/cloudflare` 捆绑 :

```ts
// src/worker.ts
import { createAppwardenMiddleware } from "@appwarden/middleware/cloudflare"

const appwardenHandler = createAppwardenMiddleware((cloudflare) => ({
  debug: cloudflare.env.DEBUG,
  appwardenApiToken: cloudflare.env.APPWARDEN_API_TOKEN,
  website: {
    lockPageSlug: cloudflare.env.APPWARDEN_LOCK_PAGE_SLUG,
    cspMode: cloudflare.env.CSP_MODE,
    cspDirectives: cloudflare.env.CSP_DIRECTIVES,
  },
  api: {
    basePaths: ["/api"],
  },
  bypassPaths: ["/health"],
}))

export default {
  fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {
    return appwardenHandler(request, env, ctx)
  },
}
```

见Cloudflare集成文件 [appwarden.io (英语)](https://appwarden.io/docs) 用于环境变量设置和部署细节.

#### 1.2 云浮框架适配器

如果您正在使用一个支持的框架, 您可以使用特定框架的适配器在应用程序中挂载 Appwarden 。 这种办法不涉及额外费用.

框架适配器还可以同步 Appwarden 管理的锁定页面和 CSP 设置到您的构建中 :

1.  添加一个构建钩, 如 `"prebuild": "appwarden-link --fqdn=your.app"`
2.  导入 `.appwarden/linked/middleware.json`
3.  通过调用将生成配置与代码级别覆盖合并 `getAppwardenConfiguration(generatedConfig, overrides)`

传入的值 `overrides` 优先于生成的配置.

##### 云层上的天体

```ts
// src/middleware.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/astro"
import { sequence } from "astro:middleware"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

const appwarden = createAppwardenMiddleware(() =>
  getAppwardenConfiguration(appwardenConfig, {
    appwardenApiToken: env.APPWARDEN_API_TOKEN,
  }),
)

export const onRequest = sequence(appwarden)
```

见 [天体+ 云花向导](https://appwarden.io/docs/guides/astro-cloudflare) 更多细节.

##### 在 Cloudflare 上反应路由器

-   设定 `future.v8_middleware: true` 在你身边 `react-router.config.ts` 文件

```ts
// app/root.tsx
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/react-router"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

export const middleware = [
  createAppwardenMiddleware(() =>
    getAppwardenConfiguration(appwardenConfig, {
      appwardenApiToken: env.APPWARDEN_API_TOKEN,
    }),
  ),
]
```

见 [反应路由器 + Cloudflare 指南](https://appwarden.io/docs/guides/react-router-cloudflare) 更多细节.

##### 在云层上开始 TanStack

```ts
// start.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/tanstack-start"
import { createMiddleware, createStart } from "@tanstack/react-start"
import { env } from "cloudflare:workers"
import appwardenConfig from "../.appwarden/linked/middleware.json"

const appwardenMiddleware = createMiddleware().server(
  createAppwardenMiddleware(() =>
    getAppwardenConfiguration(appwardenConfig, {
      appwardenApiToken: env.APPWARDEN_API_TOKEN,
    }),
  ),
)

export const startInstance = createStart(() => ({
  requestMiddleware: [appwardenMiddleware],
}))
```

见 [TanStack 启动 + Cloudflare 引导](https://appwarden.io/docs/guides/tanstack-start-cloudflare) 更多细节.

##### Next.js on Cloudflare(下个开放)

```ts
// middleware.ts or proxy.ts
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/cloudflare/nextjs"
import appwardenConfig from "./.appwarden/linked/middleware.json"

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

export default createAppwardenMiddleware((runtime) =>
  getAppwardenConfiguration(appwardenConfig, {
    appwardenApiToken: runtime.env.APPWARDEN_API_TOKEN,
  }),
)
```

此适配器应用 CSP **仅页眉** 在来源前(没有 HTML 重写,没有非ce 注射) 。 非基于CSP( CSP)`{{nonce}}`)为 **不支持** ; CSP 指令不得包括 `{{nonce}}`。 。 。 .

### 2\. 韦塞尔

要使用 Appwarden 作为 Vercel Edge Middleware, 请使用 `@appwarden/middleware/vercel` 捆绑 :

```ts
// middleware.ts (Next.js app on Vercel)
import {
  createAppwardenMiddleware,
  getAppwardenConfiguration,
} from "@appwarden/middleware/vercel"

const appwardenMiddleware = createAppwardenMiddleware(
  getAppwardenConfiguration(
    {},
    {
      // Edge Config or Upstash KV URL
      cacheUrl: process.env.APPWARDEN_CACHE_URL!,
      // Required when using Vercel Edge Config
      vercelApiToken: process.env.APPWARDEN_VERCEL_API_TOKEN!,
      appwardenApiToken: process.env.APPWARDEN_API_TOKEN!,
      debug: true,
      website: {
        lockPageSlug: "/maintenance",
        cspMode: "report-only",
        cspDirectives: {
          "default-src": ["'self'"],
        },
      },
      api: {
        basePaths: ["/api"],
      },
      bypassPaths: ["/health"],
    },
  ),
)

export default appwardenMiddleware
```

非基于CSP( CSP)`{{nonce}}`)为 **不支持** 在Vercel Edge Middleware中; CSP指令不得包括 `{{nonce}}`。 。 。 .

## 支持的平台

-   [Cloudflare上的所有网站](https://appwarden.io/docs/guides/cloudflare-middleware-integration)
    -   [云层上的天体](https://appwarden.io/docs/guides/astro-cloudflare)
    -   [在 Cloudflare 上反应路由器](https://appwarden.io/docs/guides/react-router-cloudflare)
    -   [在云层上开始 TanStack](https://appwarden.io/docs/guides/tanstack-start-cloudflare)
    -   [Next.js on Cloudflare(下个开放)](https://appwarden.io/docs/guides/nextjs-cloudflare)
-   [Vercel上的所有网站](https://appwarden.io/docs/guides/vercel-integration)

## 代理技能

这个仓库的船 [TanStack 意图](https://tanstack.com/intent) 技术 `skills/` 因此编码代理可以发现并应用 Appwarden 安装,配置,以及故障排除指导.

安装后 `@appwarden/middleware`,配置您的代理以使用这些技能 :

```bash
npx @tanstack/intent@latest install
```

可选的是,安装代理钩,因此编辑被锁定,直到一个技能被加载(Claude Code和Codex):

```bash
npx @tanstack/intent@latest hooks install
```

然后在执行任务时装入特定技能:

```bash
npx @tanstack/intent@latest load @appwarden/middleware#appwarden-middleware-get-started
```

列出现有技能:

```bash
npx @tanstack/intent@latest list
```

## 捐款

欢迎捐款! 请随意提交拉力请求.

1.  叉子存储器
2.  创建您的特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  使用 [常规武器委员会](https://www.conventionalcommits.org/) 格式
    -   此工程将执行带有 content 的信件格式
    -   实例:
        -   `feat: add new feature`
        -   `fix: resolve issue with X`
        -   `docs: update README`
        -   `chore: update dependencies`
        -   `test: add tests for feature X`
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

## 发展

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Run tests
pnpm test
```

## 警卫

请审查一下我们 [安全政策](https://npmcn.com/package/%40appwarden/middleware/SECURITY.md) 详细介绍我们如何处理脆弱性和如何报告安全问题.

这个软件包与 npm 信任的出版商一起发布,以防止 npm 令牌被过滤,并启用出处,这为出版软件包及其源代码提供了可核查的链接. 更多信息见 [npm 出处文档](https://docs.npmjs.com/generating-provenance-statements)。 。 。 .

## 版本依赖性( N)

-   这个项目使用常规承诺和自动发布工具,使版本和更改日志不断更新.
-   补丁发布可能包括错误修正和内部维护或依赖性更新(例如Cloudflare Workers类型,Wrangler,和GitHub Action工具). 新的特性在小版本中被运出.
-   见 `CHANGELOG.md` 为完整的发布历史.

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40appwarden/middleware/LICENSE) 详细文件.

## 常见问题

### @appwarden/middleware 是什么？

立即禁用 Cloudflare 或 Vercel 上部署的应用程序中的所有用户交互

### 如何安装 @appwarden/middleware？

在项目目录运行 npm install @appwarden/middleware，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 appwarden-link，可以用 npx appwarden-link 直接运行。

### @appwarden/middleware 支持 TypeScript 吗？

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

### @appwarden/middleware 支持 ESM 还是 CommonJS？

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

### @appwarden/middleware 需要什么版本的 Node\.js？

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

### @appwarden/middleware 可以商用吗？

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

### @appwarden/middleware 的下载量有多少？

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

### @appwarden/middleware 还在维护吗？

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