# uri-js 中文文档

规范地址：https://npmcn.com/package/uri-js/

版本：4\.4\.1
npm 元数据更新时间：2023-06-22T16:34:03.088Z
中文译文更新时间：2026-11-04T22:26:52.624Z
软件包许可：BSD-2-Clause

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

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

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

- 包体积（解压后）：470 kB，46 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2012-03-13T19:38:32.924Z
- 最新版本发布：2021-01-10T00:43:12.666Z
- 近 30 天下载量：615216924（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 0 个）

## 中文简介

一个RFC 3986/3987兼容，方案可扩展的URI/IRI解析/验证/解析库。

## 安装

```sh
npm install uri-js
```

也可以使用：`pnpm add uri-js`、`yarn add uri-js`、`bun add uri-js`

## README

# URI.js

js是一个 [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt) 兼容，方案可扩展的URI解析/验证/解析库，适用于所有JavaScript环境（浏览器，Node.js等）。 它也符合国际信息交换条例([RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)), idna ([RFC 5890](http://www.ietf.org/rfc/rfc5890.txt))、IPv6地址([RFC 5952](http://www.ietf.org/rfc/rfc5952.txt))、IPv6区域标识符([RFC 6874](http://www.ietf.org/rfc/rfc6874.txt))规范。

URI.js有一个广泛的测试套件，可以在所有（Node.js, web）环境中工作。它的重量为6.4kb（压缩，压缩后为17kb）。

## API

### 解析

```
URI.parse("uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body");
//returns:
//{
//  scheme : "uri",
//  userinfo : "user:pass",
//  host : "example.com",
//  port : 123,
//  path : "/one/two.three",
//  query : "q1=a1&q2=a2",
//  fragment : "body"
//}
```

### 序列化

```
URI.serialize({scheme : "http", host : "example.com", fragment : "footer"}) === "http://example.com/#footer"
```

### 解决

```
URI.resolve("uri://a/b/c/d?q", "../../g") === "uri://a/g"
```

### 正常化

```
URI.normalize("HTTP://ABC.com:80/%7Esmith/home.html") === "http://abc.com/~smith/home.html"
```

### 比较

```
URI.equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d") === true
```

### IP支持

```
//IPv4 normalization
URI.normalize("//192.068.001.000") === "//192.68.1.0"

//IPv6 normalization
URI.normalize("//[2001:0:0DB8::0:0001]") === "//[2001:0:db8::1]"

//IPv6 zone identifier support
URI.parse("//[2001:db8::7%25en1]");
//returns:
//{
//  host : "2001:db8::7%en1"
//}
```

### IRI的支持

```
//convert IRI to URI
URI.serialize(URI.parse("http://examplé.org/rosé")) === "http://xn--exampl-gva.org/ros%C3%A9"
//convert URI to IRI
URI.serialize(URI.parse("http://xn--exampl-gva.org/ros%C3%A9"), {iri:true}) === "http://examplé.org/rosé"
```

### 选项

以上所有函数都可以接受一个额外的options参数，该参数是一个对象，可以包含以下一个或多个属性：

-   `scheme` (字符串)
    
    指示URI应被视为的模式，覆盖URI的正常模式解析行为。
    
-   `reference` (字符串)
    
    如果设置为 `"suffix"`，它表明URI是后缀格式，验证器将使用该选项 `scheme` 属性来确定URI的模式。
    
-   `tolerant` (布尔,假)
    
    如果设置为 `true`，解析器将放松URI解析规则。
    
-   `absolutePath` (布尔,假)
    
    如果设置为 `true`时，序列化程序将不解析相对类型 `path` 组件。
    
-   `iri` (布尔,假)
    
    如果设置为 `true`，序列化器将按照要求对非ascii字符进行转义 [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)。
    
-   `unicodeSupport` (布尔,假)
    
    如果设置为 `true`，解析器将按顺序对解析输出中的非ascii字符进行转义 [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)。
    
-   `domainHost` (布尔,假)
    
    如果设置为 `true`，图书馆会招待的 `host` 组件作为域名，并转换idn（国际域名） [RFC 5891](http://www.ietf.org/rfc/rfc5891.txt)。
    

## 方案可扩展

js支持插入自定义 [计划](http://en.wikipedia.org/wiki/URI_scheme) 依赖的处理规则。目前，URI.js内置了对以下方案的支持：

-   http \[[RFC 2616](http://www.ietf.org/rfc/rfc2616.txt)］
-   https ([RFC 2818](http://www.ietf.org/rfc/rfc2818.txt)］
-   ws ([RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)］
-   wss ([RFC 6455](http://www.ietf.org/rfc/rfc6455.txt)］
-   mailto \[[RFC 6068](http://www.ietf.org/rfc/rfc6068.txt)］
-   缸([RFC 2141](http://www.ietf.org/rfc/rfc2141.txt)］
-   urn: uuid ([RFC 4122](http://www.ietf.org/rfc/rfc4122.txt)］

### HTTP / HTTPS支持

```
URI.equal("HTTP://ABC.COM:80", "http://abc.com/") === true
URI.equal("https://abc.com", "HTTPS://ABC.COM:443/") === true
```

### WS / WSS支持

```
URI.parse("wss://example.com/foo?bar=baz");
//returns:
//{
//	scheme : "wss",
//	host: "example.com",
//	resourceName: "/foo?bar=baz",
//	secure: true,
//}

URI.equal("WS://ABC.COM:80/chat#one", "ws://abc.com/chat") === true
```

### Mailto支持

```
URI.parse("mailto:alpha@example.com,bravo@example.com?subject=SUBSCRIBE&body=Sign%20me%20up!");
//returns:
//{
//	scheme : "mailto",
//	to : ["alpha@example.com", "bravo@example.com"],
//	subject : "SUBSCRIBE",
//	body : "Sign me up!"
//}

URI.serialize({
    scheme : "mailto",
    to : ["alpha@example.com"],
    subject : "REMOVE",
    body : "Please remove me",
    headers : {
        cc : "charlie@example.com"
    }
}) === "mailto:alpha@example.com?cc=charlie@example.com&subject=REMOVE&body=Please%20remove%20me"
```

### URN的支持

```
URI.parse("urn:example:foo");
//returns:
//{
//	scheme : "urn",
//	nid : "example",
//	nss : "foo",
//}
```

#### URN UUID支持

```
URI.parse("urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6");
//returns:
//{
//	scheme : "urn",
//	nid : "uuid",
//	uuid : "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
//}
```

## 用法

要在浏览器中加载，请使用以下标签：

```
<script type="text/javascript" src="uri-js/dist/es5/uri.all.min.js"></script>
```

要在CommonJS/Module环境中加载，首先使用npm/yarn在命令行上运行：

```
npm install uri-js
# OR
yarn add uri-js
```

然后，在你的代码中，使用：

```
const URI = require("uri-js");
```

如果你用ES6+ (ESNEXT)或TypeScript编写代码，你可以使用：

```
import * as URI from "uri-js";
```

或者你可以使用named exports加载你需要的东西：

```
import { parse, serialize, resolve, resolveComponents, normalize, equal, removeDotSegments, pctEncChar, pctDecChars, escapeComponent, unescapeComponent } from "uri-js";
```

## 打破变化

### 打破3.x的变化

URN解析已经完全改变，以更好地与规范保持一致。计划现在总是 `urn`，但有两个新属性： `nid` 其中包含命名空间标识符，以及 `nss` 其中包含命名空间特定字符串。这个 `nss` 属性将被更高阶的方案处理程序（如UUID URN方案处理程序）删除。

URN的UUID现在可以在 `uuid` 财产。

### 打破2.x的变化

URI验证被删除了，因为它速度慢，暴露了一个漏洞，而且通常没有用处。

### 打破1.x的变化

这个 `errors` 已解析组件上的数组现在是 `error` 字符串。

## 常见问题

### uri-js 是什么？

一个RFC 3986/3987兼容，方案可扩展的URI/IRI解析/验证/解析库。

### 如何安装 uri-js？

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

### uri-js 支持 TypeScript 吗？

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

### uri-js 支持 ESM 还是 CommonJS？

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

### uri-js 可以商用吗？

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

### uri-js 的下载量有多少？

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

### uri-js 还在维护吗？

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