# @apostrophecms/redirect 中文文档

规范地址：https://npmcn.com/package/%40apostrophecms/redirect/

版本：1\.7\.1
npm 元数据更新时间：2026-10-20T16:57:35.472Z
中文译文更新时间：2026-11-06T21:21:29.210Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：61.8 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-06-25T14:38:18.686Z
- 最新版本发布：2026-09-30T19:28:54.887Z
- 近 30 天下载量：2323（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 5 个）

## 中文简介

管理 ApostropeCMS 的定向

## 安装

```sh
npm install @apostrophecms/redirect
```

也可以使用：`pnpm add @apostrophecms/redirect`、`yarn add @apostrophecms/redirect`、`bun add @apostrophecms/redirect`

## README

![ApostropheCMS logo](https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg)

# 管理 ApostropeCMS 的站点重定向

 [![](https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge&logo=Apostrophe&labelColor=6516dd)](https://docs.apostrophecms.org/)[![](https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20) ](http://chat.apostrophecms.org/)[![](https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639)](https://github.com/apostrophecms/apostrophe/blob/main/packages/redirect/LICENSE.md)

## 安装

先确保你有一个 [Aposrope项目](https://apostrophecms.com/)来啊!

然后说:

```javascript
npm install @apostrophecms/redirect
```

## 配置

单位 `app.js`,在配置中添加模块:

```js
require('apostrophe')({
  shortName: 'MYPROJECT',
  modules: {
    '@apostrophecms/redirect': {}
  }
});
```

### `statusCode`

_默认为 `302`_ 路过 `statusCode` 到您的配置时,您可以更改默认状态代码值. 接受数值为 `301` 财务报告和审定财务报表 `302`

```javascript
// Other modules, then...
'@apostrophecms/redirect': {
  options: {
    statusCode: 301
  }
}
```

> 注意永久重定向被谷歌缓存很长时间. 最好鼓励用户先用一个临时的重定向进行测试,然后切换到永久,这是SEO的最佳做法——只要它是正确的.

### `withType`

_默认为 `@apostrophecms/page`_ 路过 `withType` 到您的配置中,您可以指定您内部重定向可以重定向的文档类型.

```javascript
// Other modules, then...
'@apostrophecms/redirect': {
  options: {
    withType: 'article'
  }
}
```

**说明:** Aposfrope 2支持从单一界面创建多个 doc类型的关系. 这个功能在较新的Aposrope版本中尚不存在,因为这样的重定向只能指定一个单一的doc类型来重定向.

### `skip`

对于性能,可以跳过匹配某些正则表达式的 URL 重定向检查 . 默认配置 `skip` 选项是:

```javascript
// Other modules, then...
'@apostrophecms/redirect': {
  options: {
    skip: [ /\/api\/v1\/.*/ ]
  }
}
```

如果你想跳过其他模式,我们建议保留默认模式,因为它可以加速API的呼叫.

### `caseInsensitive`

_默认为 `false`_

路过 `caseInsensitive: true` 中,每个方向的“旧 URL”与收到的请求的 URL 匹配,而不考虑大小写。 当从一个对大小写不敏感(例如 IIS)的网络服务器迁移时,这样做是有用的,因为该服务器的重定向规则可能已经输入了混合大小写弹片,例如 `/Events` 或者说 `/About-Us/Partners`,但入境流量(旧书签、搜索引擎结果、外部链接)可能携带任何外壳抵达,例如 `/events` 或者说 `/EVENTS`。 。 。 .

```javascript
// Other modules, then...
'@apostrophecms/redirect': {
  options: {
    caseInsensitive: true
  }
}
```

当启用此选项时 :

-   新的和已编辑的重定向器将它们的"旧 URL"自动存储在小写中.
-   迁移运行到任何已存在的重定向的“ 旧 URL ” 小写 .
-   来信请求 URL 在与存储的重定向相匹配之前会小写(在将通配符替换为目的地 URL时仍然使用请求的原始外壳).

⚠️ **此选项不支持“ 混合” 大小写敏感和大小写不敏感重定向 .** 允许它小写所有已存在的“ 旧 URL” 值, 此迁移是 **不可逆变**。如果您以后停止操作 `caseInsensitive`,您先前存在的重定向将只匹配小写请求 URL,因为它们所存储的"旧 URL" 值仍然是小写 。 如果这对您有关系, 您需要手动重新创建受影响的重定向器, 并使用其原有的混合大小写“ 旧 URL ” 值 .

## 使用量

在登录为管理员时,单击"重定向"按钮. 显示方向列表, 初始为空 。 添加您喜欢的 。 "来自" URL 必须从 `/`。“to” URL可能是任何东西,不需要在您的网站上。 "叙事"场为自取.

### 匹配查询字符串

默认情况下,重定向包含任何查询字符串(即 `?` 和任何随行,直到但不包括任何 `#`在匹配重定向时收到的请求.

您可以在重定向定义中切换“ 匹配时忽略查询字符串” 选项, 以忽略所收到请求的查询字符串, 并且只匹配基础 URL 路径 。 不使用此选项的重定向将总是首先匹配,这样您就可以匹配各种特定的查询字符串,然后对其他案例有倒置规则.

### 匹配通配符

通常,除了查询字符串之外,只有精确的匹配才能被尊重. 如果您想重定向整个子目录,您可以使用 `*` 紧接着 `/`,例如:

```
/auto/*
```

这会改变方向 **全部** 开始的 URL `/auto/` 到目的地,像这样:

```
/auto/hyundai -> /fr/auto
/auto/hyundai/ioniq-5 -> /fr/auto
```

请注意这一点 **丢弃 URL 的其余部分**。如果这不是你想要的,请参见下文.

### 准确匹配总是赢

如果你有方向调整规则 没有 `*`它总是会用 `*`。 。 。 .

例如,如果你有这样的规则:

```
/auto/gm/bolt -> /en/auto/gm/bolt
/auto/* -> /fr/auto
```

那么实际的重定向会像这样进行:

```
/auto/gm/bolt -> /en/auto/gm/bolt
/auto/toyota/tercel -> /fr/auto
```

### 抓取通配符

如果您正在创建“ URL” 重定向, 而不是“ Internal Page ” , 您也可以“ 抓取” 并重新使用 URL 的其余部分 `*` 。当 URL 的其余部分仍然正确时,此操作是有用的.

例如,如果您的“ 旧 URL ” 是:

```
/auto/*
```

在“URL”字段中,您选择“URL”作为重定向类型,并按以下键:

```
/fr/auto/*
```

然后重定向会像这样发生:

```
/auto/hyundai -> /fr/auto/hyundai
/auto/hyundai/ioniq-5 -> /fr/auto/hyundai/ioniq-5
```

### 创建带有多通配符规则的倒置

请注意,如果有两项重定向规则涉及 `*` 一个比另一个长, **越长的比赛总能赢.**

例如,如果您的方向调整是这样设置的:

```
/auto/hyundai/* -> /en/car/hyundai/*
/auto/* -> /fr/auto/*
```

然后重定向会像这样进行:

```
/auto/mercedes -> /fr/auto/mercedes
/auto/mercedes/w123 -> /fr/auto/mercedes/w123
/auto/hyundai -> /en/car/hyundai
/auto/hyundai/ioniq-5 -> /en/car/hyundai/ioniq-5
```

### 安全问题

注意,每次方向调整都会在保存后立即活下来,并且有可能搞出方向调整的混乱. 一些明显的危险,如改变方向 `/*` 或者说 `/api/v1/*` 但还是有可能造成问题, 中, 您可以通过 MongoDB 命令行客户端删除不想要的重定向( 请查看 ) `{ type: "@apostrophecms/redirect" }` 输入 `aposDocs` 收藏于MongoDB).

### 软重定向: 当您不需要此模块时

为方便您起见, AposfropeCMS 每次更改一页或一行的相片时都会自动创建"软重定向",条件是文档在旧的URL至少访问一次. 因此,你不需要手动 创建一个"硬方向调整"在这种情况下.

## 扩展模块

### 提供后退处理器

如果您想以另一种方式处理此模块找不到匹配的重定向, 您可以通过监听 `@apostrophecms/redirect:noMatch` 活动。 此事件处理器收到 `req, result`。发布方向调整,设置 `result.redirect` 在您的事件处理者。 发布“ raw” 重定向, 任何全站前缀都不会自动附加, set `result.rawRedirect` 在您的事件处理者。 您也可以设置 `result.status` 以匹配您的需要, 作为重定向状态代码, 默认是 `302`。 。 。 .  
如果您想在重定向即将来临时更改目标url, 例如改变域名, 您可以听 `@apostrophecms/redirect:beforeRedirect`。此事件处理器收到 `req, result`。 。 。 . `result` 在重定向前, 将有两个属性可以更改 : `status` 财务报告和审定财务报表 `url`。 。 。 . **别** 调用 `req.res.redirect()` 在那两起案子中 自己负责办案.

例如:

```javascript
// modules/redirect-fallback/index.js
module.exports = {
  handlers(self) {
    return {
      '@apostrophecms/redirect:noMatch': {
        // will be awaited, you can do queries here if needed
        async fallback(req, result) {
          if (req.url.match(/pattern/)) {
            result.redirect = '/destination';
          }
        }
      }
    }
  }
}
```

### 防止重定向模块

如果您的目标是通过决定在某些情况下在本模块寻找匹配之前以不同方式重定向来先发制人本模块,注册你自己的中间软件并在那里执行重定向. 使用 `before` 指定您自己的模块的中间软件是先到的.

例如:

```javascript
// modules/early-redirect/index.js
module.exports = {
  middleware(self) {
    return {
      earlyRedirect: {
        before: '@apostrophecms/redirect',
        middleware(req, res, next) {
          if (req.url.match(/pattern/)) {
            return res.redirect('/destination');
          } else {
            return next();
          }
        }
      }
    };
  }
};
```

### 更快地执行中间软件

默认情况下,检查重定向的本模块中间软件将视本模块在模块配置中的位置而执行.  
您可以通过设置 `before` 选项,说明该模块应当运行哪个模块中间软件(例如) `@apostrophecms/global`) (中文(简体) ).  
请注意,通过这样做,上述先发制人的做法将不再有效.

## 重定向到其它地方

有可能从一个地方转向另一个地方, 有外部的再定向, 既然您手动定义了 url 可以重定向到 .

至于内部改道(与页面的关系),这在各地也有作用, 但记住,只有在管理重定向时,您才会看到针对当前地段的内部重定向. 要找到针对不同地段内部页面的重定向,在收看"管理重定向"前切换地段

给开发者的注释: 调用查询构建器 `currentLocaleTarget` 隐藏与其它地块有关系的重定向(不同于当前地块). 如果您想要获得所有重定向, 无论其内部重定向的用地是什么, 您可以使用查询构建器来撤消这种行为 :

```javascript
const redirects = await self.apos.modules['@apostrophecms/redirect']
    .find(req)
    .currentLocaleTarget(false)
    .toArray();
```

## 常见问题

### @apostrophecms/redirect 是什么？

管理 ApostropeCMS 的定向

### 如何安装 @apostrophecms/redirect？

在项目目录运行 npm install @apostrophecms/redirect，或使用 pnpm add / yarn add / bun add。

### @apostrophecms/redirect 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apostrophecms\_\_redirect 是否存在。

### @apostrophecms/redirect 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apostrophecms/redirect 可以商用吗？

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

### @apostrophecms/redirect 的下载量有多少？

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

### @apostrophecms/redirect 还在维护吗？

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