@xesam/url

English | 简体中文

面向受限运行环境（小程序等）的类 URL 字符串拆分器。零依赖、纯 ES5、单正则实现。

为什么需要它

小程序等受限 JavaScript 运行环境通常有以下特点，使标准 URL 对象或第三方解析库难以直接使用：

• 没有可靠的 URL 构造器：微信、支付宝等小程序运行时无法稳定提供 WHATWG 标准的 URL；
• 对包体积极其敏感：微信小程序主包体积上限为 2MB，没有余量为解析一个 URL 引入 polyfill 级别的大库；
• 要求 ES5 兼容：低版本基础库与部分运行环境不支持 ES6+ 语法。

@xesam/url 的取舍是：只支持两类最常见的输入形态，用一条正则完成拆分，换来几百字节的体积与绝对稳定的行为。

典型使用场景：

• 解析分享卡片、小程序码（scene 参数）等入口链接中的参数；
• 解析 H5 跳转小程序时下发的 path 字符串；
• 分发自定义 scheme:// 协议的跳转路由；
• 在小程序内拆解 WebView 承载的业务链接。

安装

npm install @xesam/url

同时提供 CommonJS（require）与 ES Module（import）入口，详见 package.json 的 exports 字段。

快速上手

const url = require('@xesam/url');

console.log(url('https://admin:[email protected]:443/path/to/view?tab=home#top'));
console.log(url('miniapp://page.example/path/to/view?tab=home#top'));
console.log(url('/pages/home/index?tab=home#top'));
console.log(url('?query-only'));
console.log(url('#hash-only'));
console.log(url('????'));

以 https://admin:[email protected]:443/path/to/view?tab=home#top 为例：

{
    protocol: 'https:',
    auth: 'admin:root',
    host: 'page.example:443',
    hostname: 'page.example',
    port: '443',
    pathname: '/path/to/view',
    search: '?tab=home',
    query: 'tab=home',
    hash: '#top'
}

其余示例中非 undefined 的字段：

| 输入 | 非 undefined 的字段 | |---|---| | miniapp://page.example/path/to/view?tab=home#top | protocol: 'miniapp:'、host / hostname（'page.example'）、pathname、search、query、hash | | /pages/home/index?tab=home#top | pathname: '/pages/home/index'、search: '?tab=home'、query: 'tab=home'、hash: '#top' | | ?query-only | search: '?query-only'、query: 'query-only' | | #hash-only | hash: '#hash-only' | | ???? | 无（九字段全为 undefined） |

支持的输入形态

• scheme://[auth@]host[:port][/path][?query][#hash]
• /path[?query][#hash]

?query-only 与 #hash-only 是文档化的边界行为：前者返回 search 与 query 字段，后者返回 hash 字段。

明确不支持的输入

• 无 authority 的 scheme URI，如 mailto:[email protected]
• 无 authority 的 payload scheme，如 data:text/plain,hello
• 脚本类 scheme，如 javascript:alert(1)
• 协议相对地址，如 //example.com/path（原样落入 pathname，不承诺解析）

对以上不支持的输入类：本库不抛错，但返回的字段值不构成契约的一部分。

返回值契约（永不抛错）

任何一次调用都返回同一个稳定的对象结构，包含以下九个字段：

protocol、auth、host、hostname、port、pathname、search、query、hash

• 支持的输入形态与文档化的边界行为：按匹配结果填充字段，其余字段为 undefined；
• 畸形、空白（空串或纯空白字符）、nullish、未匹配的输入：统一降级为九字段全 undefined 的固定对象。

在受限运行环境里，一个未捕获的异常可能直接导致页面白屏。因此本库选择「固定结构 + 降级」的失败模式，而不是异常驱动的失败。

字段说明

以 https://admin:[email protected]:443/p/a?tab=home#top 为例：

| 字段 | 说明 | 示例值 | |---|---|---| | protocol | 协议，含冒号 | 'https:' | | auth | 认证信息（用户名:密码），不含 @ | 'admin:root' | | host | hostname + port | 'page.example:443' | | hostname | 主机名，不含端口 | 'page.example' | | port | 端口，字符串形式 | '443' | | pathname | 路径，以 / 开头 | '/p/a' | | search | 查询串，含 ? | '?tab=home' | | query | 查询串，不含 ? | 'tab=home' | | hash | 锚点，含 # | '#top' |

与标准 URL 解析器的差异（非目标）

@xesam/url 不是标准合规的 URL 解析器，不提供：

• RFC / WHATWG 合规保证（IPv6 host 等边界不承诺支持）
• 校验（validity）
• 规范化（normalization）
• 百分号解码（percent-decoding）
• 序列化 / 重组（formatting）

FAQ

为什么解析失败不抛错，而是返回全 undefined 的对象？ 小程序等环境中未捕获异常的代价高（白屏、崩溃）。固定结构让调用方可以用一致的判空逻辑处理所有失败路径。

为什么 mailto:、data:、javascript: 不支持？ 本库只拆分「带 authority（://）的类 URL」，不做通用 URI 解析。这类输入会降级为全 undefined 的空对象。

为什么 //example.com/path 不按 host 解析？ 协议相对地址属于明确不支持的输入类，会原样保留在 pathname 中（如 pathname: '//example.com/path'），这是被测试保护的文档化行为。

和 Node.js 的 url.parse / WHATWG URL 有什么区别？ 本库是极小的拆分器：只拆分、不校验、不规范化、不解码、不重组，且输出结构在任何输入下都稳定。标准解析器的合规性与能力不在目标内。

从 0.1.3 升级到 0.1.4 需要注意什么？ 0.1.4 是破坏性变更：空 / 无效输入不再返回 {}，而是返回九字段全 undefined 的固定对象。依赖 !url(x) 这类真值判断的代码，需要改为字段级判断。

开发

npm test      # 运行测试
npm run build # 构建产物到 dist/

许可证

MIT