# @fedify/uri-template 中文文档

规范地址：https://npmcn.com/package/%40fedify/uri-template/

版本：2\.4\.6
npm 元数据更新时间：2026-11-17T10:39:48.931Z
中文译文更新时间：2026-11-17T10:40:11.407Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fedify/uri-template
原文对照：https://npmcn.com/package/%40fedify/uri-template/?lang=original
项目主页：https://fedify.dev/
源码仓库：https://github.com/fedify-dev/fedify

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

- 包体积（解压后）：222 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- 首次发布：2025-11-04T08:03:07.173Z
- 最新版本发布：2026-11-17T10:39:48.498Z
- 近 30 天下载量：64464（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：238（近 12 个月 237 个）

## 中文简介

RFC 6570 URI 模板扩展和回合模式匹配

## 安装

```sh
npm install @fedify/uri-template
```

也可以使用：`pnpm add @fedify/uri-template`、`yarn add @fedify/uri-template`、`bun add @fedify/uri-template`

## README

# @fedify/uri-template: Counter-trip RFC 6570 URI (英语). 模板库

[![JSR](https://jsr.io/badges/@fedify/uri-template)](https://jsr.io/@fedify/uri-template) [![npm](https://img.shields.io/npm/v/@fedify/uri-template?logo=npm)](https://www.npmjs.com/package/@fedify/uri-template)

此软件包提供了 [RFC 6570 (法语)](https://datatracker.ietf.org/doc/html/rfc6570) 执行的 URI 模板执行 扩展和图案都与往返验证相匹配。 这是其中的一部分 页:1 [联邦](https://fedify.dev/) 框架,但可以独立使用.

## 为什么 `@fedify/uri-template`? 吗?

合并以前依赖两个独立的第三方实施: [url 模板](https://www.npmjs.com/package/url-template) 用于 URI 模板扩展和 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router) 页:1 路径匹配. `@fedify/uri-template` 用一个严格的RFC 6570取代两者 解析器和一个扩展/匹配模型.

### 为什么替换 [url 模板](https://www.npmjs.com/package/url-template) 与 `Template`? 吗?

[url 模板](https://www.npmjs.com/package/url-template) 自我描述为 RFC 6570 执行,但其行为 并不足以满足Fedify的URI路由和往返匹配需求. 测试在 _旧/url-template.ts_ 记录与 `npm:url-template@^3.1.1`。 。 。 .

主要的失败是:

-   它以可变名称命名时的 pct-encod 三重码 运算符发出可变名称。 譬如说, `{?abc%20def}` 扩展至 `?abc%2520def=spaced` 改为 `?abc%20def=spaced`。 。 。 . [RFC 6570 第2.3节](https://datatracker.ietf.org/doc/html/rfc6570#section-2.3) 允许 `pct-encoded` 内部 `varname` 并把它当作 变量名称. [RFC 6570 第3.2.8节](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.8) 以字面形式发出变量名称 字符串,以及 [RFC 6570 第2.1节](https://datatracker.ietf.org/doc/html/rfc6570#section-2.1) 许可 `pct-encoded` 字义. 因此 `%20` 财务报告和审定财务报表 `%41` 必须保存,不得再次编码为 `%2520` 财务报告和审定财务报表 `%2541`。 。 。 .
-   它接受畸形模板而不是报告语法错误. [RFC 6570 第2节](https://datatracker.ietf.org/doc/html/rfc6570#section-2) 要求用匹配的括号来定义表达式, [RFC 6570 第2.1节](https://datatracker.ietf.org/doc/html/rfc6570#section-2.1) 不包括原始括号、控制字符、空格、原始 `%` 除了一个被编码的三胞胎 和其他被禁的字形字符之外 [RFC 6570 第3节](https://datatracker.ietf.org/doc/html/rfc6570#section-3) 表示语法错误应显示其位置和类型 适用于援引的申请. `@fedify/uri-template` 报告这些案件为: 输入错误.
-   它对列表和 关联阵列. [RFC 6570 第2.4.1节](https://datatracker.ietf.org/doc/html/rfc6570#section-2.4.1) 表示前缀修改符不是 适用于具有复合值的变量,因此 `{list:3}`, (中文(简体) ), `{keys:3}`, (中文(简体) ), 财务报告和审定财务报表 `{count:2}` 必须失败.

`Template` 被写成一个新的执行而不是包 [url 模板](https://www.npmjs.com/package/url-template) 因为 Fedify 需要严格的 RFC 6570 扩展, 键入语法 错误,以及往返检查的匹配行为. 需要申请 较宽松的剖析器可以明确选择: `strict: false` 传阅和扩展 错误到 `report` 没有扔, 和习惯 `report` 函数可以允许 所有出错或只为所选出错类别投出.

### 为什么替换 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router) 与 `Router`? 吗?

上一个路由器形状结合了两个独立的第三方 执行: [url 模板](https://www.npmjs.com/package/url-template) 用于构建 URL 和 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router) 页:1 匹配 URL. _(原始内容存档于2013-10-12). old/uri-template-router.ts_ 定义旧形状为 尽可能紧密地使差异可见于同一路由 API 下.

重要的区别是:

-   构建、匹配和可变提取均使用相同的严格RFC 6570 par. 上一个路由器以 [url 模板](https://www.npmjs.com/package/url-template) 但与之相匹配的是 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router),因此一个值可以通过一个执行编码 由另一个有不同规则的人解码.
-   路线匹配已检查 。 只接受候选路线 当恢复的值被扩展回精确输入URI时. 这个拒绝 符合解码后看起来合理但不能复制的 (原始内容存档于2013-10-10). Introduct URI. 默认情况下,匹配与输入的URI精确. `trailingSlashInsensitive` 能够使用更松散的路径查找 跟踪斜线差异,然后进行相同的回程检查.
-   Pct-encoded 三胞胎被保存在RFC 6570将其当作语法处理的地方. 字形三进制, pct- 编码可变名称, 并命名查询参数 例如 `{?abc%20def}` 保留 `%20` 而不是成为 `%2520`。 。 。 .
-   预留的扩展值保持其编码形式,如果 (原始内容存档于2013-10-12). URI introduct. 在之前的匹配路径下, `/files/a%2Fb` 可能会 报告为 `a/b`, (中文(简体) ), `/files/%30%23` 作为 `0#`,且已编码的 UTF-8 octets 为 Unicode 文本 。 这些值不绕行到原始URI 同样的模板.
-   路径模板由 `Router.compile()` 登记前. 独立的路由器接受普通的斜线前缀路径和 引导路径扩展窗体——以 `{/var}` 表达式,例如 `{/identifier}/inbox`。接受这种形状是一种 独立路线能力,独立于联邦:联邦 调度器路由对所需的标识符适用非空约束 (单位:千美元)`nullable` 默认为 `false`),因此是一条领先的路径扩展路线 注册,但仅在变量实际绑定时匹配 对于召回的路由,联邦建设者可能会拒绝这种形状 合同需要混凝土 `identifier`。 。 。 .
-   `Router.variables()` 财务报告和审定财务报表 `Router.compile()` 显示可变提取 不改变路由器。 遗产 `Router.add()` 返回变量为 登记路线的副作用.
-   候选人查询将符号级状态三进制和倒置前缀相结合 翠丝 可索引路径模板——其表达式各有一个 变量 `""`, (中文(简体) ), `/`,或 `+` 操作员,永远不要直接坐着 与另一个表达方式相邻 翠丝 无法安全索引的形状会回到前缀 trie 键入每个路由的初始字面前缀。 两者的候选人 尝试被合并,去重复, 按字面顺序命令 长度、初始字面前缀长度、可变数和插入顺序 在轮回比赛前.
-   克隆和路由替换不取决于复制可变个人 状态从 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router)。路由器存储编译的模板和 活动路由条目直接, 使执行保持独立 和无依赖的运行时间.

与以前相比的具体差异 [url 模板](https://www.npmjs.com/package/url-template) 财务报告和审定财务报表 [里- 后期- 路由器](https://www.npmjs.com/package/uri-template-router) 库被编码为只兼容寄存器 试验 _软件包/设备/旧/旧_ 中. 这些测试在运行时故意失败 `deno task test:old` 因为他们 对 Fedify 的预期行为执行旧的库并记录 已知的遗产差距.

## 特征

-   所有表达式类型的全RFC 6570扩展 (单位:千美元)`{var}`, (中文(简体) ), `{+var}`, (中文(简体) ), `{#var}`, (中文(简体) ), `{.var}`, (中文(简体) ), `{/var}`, (中文(简体) ), `{;var}`, (中文(简体) ), `{?var}`, (中文(简体) ), `{&var}`(中文(简体) )
-   与镜像扩展匹配的圆通模式:何时 `match(uri)` 返回数值, `expand(values) === uri`
-   可变匹配制约(`nullable`, (中文(简体) ), `multiple`安全带 默认
-   严格无脚本类型 `any` 在公众表面
-   零运行时间依赖关系

## HTTP 路径相容性

一些HTTP客户端,包括Mastodon,解码 `%3A` 改为 `:` 在请求路径中. 过 `{ allowUnencodedColon: true }` 改为 `Router.route()` 以接受字义 在可变值中冒出可扩展值 `%3A`数字 :

```typescript
const router = new Router([["/users/{identifier}", "actor"]]);
router.route("/users/alice:work", { allowUnencodedColon: true });
// { name: "actor", template: "/users/{identifier}",
//   values: { identifier: "alice:work" } }
```

精确匹配,包括配置的后继斜线重试,优先进行 超过与结肠相匹配的匹配。 文字模板文本仍然完全匹配, 和其他百分数编码字符保持其现有的匹配规则. 当模板使用冒号来分隔变量时,在数值中解码出冒号 可使边界模糊; 匹配遵循已有的后轨 秩序。 秩序.

为收到的HTTP请求提供此选项。 URI 生成和 `Context.parseUri()` 保持他们现有的行为。 独立 `Template.match()` 财务报告和审定财务报表 `Router.route()` 没有选择权,也保持精确.

## 路线可变制约因素

`Router` 登记每个 RFC 6570 运算符,但匹配受到限制 每个模板变量. `Router.add()`, (中文(简体) ), `Router.register()`,则 构造器,以及 `Router.from()` 接受路由为 `[pathOrPattern, name, options?]` tuple,其中可选的第三个元素 是每条路由选项对象 :

```typescript
import { Router } from "@fedify/uri-template";

const router = new Router();
router.add("/users/{identifier}", "actor");
router.add("/search{?q}", "search", {
  variables: { q: { nullable: true } },
});
```

`options.variables` 将变量名称映射到部分约束; 任何 字段中省略到默认值,任何模板变量 不列出清单仍然受到所有违约限制的限制。 这个 制约领域是:

-   **`nullable`** 默认为 `false`: 未绑定或绑定的变量 改为空值使路由不匹配(路由器返回到 下一个候选人。 过 `{ nullable: true }` 选择退出,所以 可选运算符,例如 `{?q}` 可能与 `q` 缺席。 因为 此默认路径、可选操作路径和主路径扩展路径 注册成功, 但仅在变量实际时匹配 现相而无空相.
-   **`multiple`** 来源于可变规格:爆炸 (单位:千美元)`{tags*}`隐含 `true` 并绑定 `readonly string[]`; 前缀 修改者(`{id:3}`隐含 `false`; 普通变量默认为 `false` (有约束力) `string`但无论哪种方式,都可以设定。 指定a `multiple` 与衍生值相矛盾,或使用相同的 具有相冲突爆炸/前缀修改器的可变名称(`{x}` 财务报告和审定财务报表 `{x*}`),投掷 `ConflictingVarSpecError` 在注册时间.
-   **`duplicable`** 默认为 `false`: 一个变量,出现在更多 大于同一模板内的一个可变规格 `DuplicateRouteVariableError` 在注册时间。 准备吧 `true` (a) 允许重复发生 URI 匹配 .
-   **`prefixable`** 默认为 `false`(单位:千美元) `{var:N}` 前缀修改符 规格抛出 `DisallowedVarSpecModifierError` 除非 变量已标记 `{ prefixable: true }`。 。 。 .
-   **`explodable`** 默认为 `false`: 这是一个 _登记 权限_,而不是输出形状声明。 A 类 `{var*}` 爆炸修改器规格抛出 `DisallowedVarSpecModifierError` 除非该变量被标记 `{ explodable: true }`; 选项 本身不会将一个值变成列表。 一个值成为 `readonly string[]` 仅在模板实际使用爆炸时 修改者(`{var*}`),因为这个 verspec 是决定 `multiple` 改为 `true`。同样的 `{ explodable: true }` 设定在非爆炸光谱上 例如 `/users/{id}` 仍会绑起平板 `string` 在运行时间.
-   **`operatables`** 默认为 `[]`,允许每个操作员. 当设置为非空运算符列表时( W)`""`, (中文(简体) ), `"+"`, (中文(简体) ), `"#"`, (中文(简体) ), `"."`, (中文(简体) ), `"/"`, (中文(简体) ), `";"`, (中文(简体) ), `"?"`, (中文(简体) ), `"&"`),使用任意运算符下的变量 列表外抛出 `DisallowedOperatorError` 登记时 时间.

选项对象也接受 **`exact`**,默认为 `true`数字 : 当你提供 `variables` 对象,其密钥必须匹配模板的 变量 – 每个模板变量必须列出,没有未知 密钥可能出现, 否则注册丢弃 `RouteTemplateOptionsNotMatchedError`设置 `{ exact: false }` 放松点 如此未列出的变量保持其默认值,未知的密钥是 被忽略 。 未注册的路由 `variables` 对象不受影响 并保持所有默认值.

```typescript
const router = new Router();

// Throws RouteTemplateOptionsNotMatchedError: `id` is not listed.
router.add("/posts/{slug}/{id}", "post", {
  variables: { slug: { nullable: true } },
});

// OK: opt out of the exact-keys check.
router.add("/posts/{slug}/{id}", "post", {
  exact: false,
  variables: { slug: { nullable: true } },
});

// OK: explode requires opting in.
router.add("/tags{/tags*}", "tags", {
  variables: { tags: { explodable: true } },
});
```

`Router.route()` 通用于约束图,所以 `values` 缩进 因此:

```typescript
const constraints = {
  identifier: { nullable: false, multiple: false },
} as const;
router.add("/users/{identifier}", "actor", { variables: constraints });

const matched = router.route<typeof constraints>("/users/alice");
if (matched != null) {
  const id: string = matched.values.identifier;
}
```

收缩类型来源于 `multiple` 财务报告和审定财务报表 `nullable` 只是,从来没有 从 `explodable`。自 `explodable` 管辖登记,而不是 解析值形状,爆炸路线必须携带 `multiple: true` 在类型参数中——不仅仅是 `explodable: true`\- 因为 `values` 缩小 改为 `readonly string[]`数字 :

```typescript
const tagConstraints = {
  tags: { explodable: true, multiple: true },
} as const;
router.add("/tags{?tags*}", "tags", { variables: tagConstraints });

const matched = router.route<typeof tagConstraints>("/tags?tags=a&tags=b");
if (matched != null) {
  const tags: readonly string[] = matched.values.tags;
}
```

## 安装

```bash
deno add jsr:@fedify/uri-template  # Deno
npm  add     @fedify/uri-template  # npm
pnpm add     @fedify/uri-template  # pnpm
yarn add     @fedify/uri-template  # Yarn
bun  add     @fedify/uri-template  # Bun
```

## 常见问题

### @fedify/uri-template 是什么？

RFC 6570 URI 模板扩展和回合模式匹配

### 如何安装 @fedify/uri-template？

在项目目录运行 npm install @fedify/uri-template，或使用 pnpm add / yarn add / bun add。

### @fedify/uri-template 支持 TypeScript 吗？

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

### @fedify/uri-template 支持 ESM 还是 CommonJS？

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

### @fedify/uri-template 需要什么版本的 Node\.js？

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

### @fedify/uri-template 可以商用吗？

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

### @fedify/uri-template 的下载量有多少？

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

### @fedify/uri-template 还在维护吗？

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

