Web URI 编码

October 19, 2025

前言

encodeURIComponent() 和 URLSearchParams 都可用于 URI 组件编码。目前，前者由 ECMA262 定义，后者由 HTML 标准定义。

RFC3986 定义的 URI 组件如下：

  foo://example.com:8042/over/there?name=ferret#nose
  \_/   \______________/\_________/ \_________/ \__/
   |           |            |            |        |
scheme     authority       path        query   fragment
   |   _____________________|__
  / \ /                        \
  urn:example:animal:ferret:nose

备注：某些 scheme 的组件在 URL 对象中会被特殊处理（scheme 为：ftp/file/http/https/ws/wss）。

new URL("http://domain域.域").toString();
// => "http://xn--domain-u21k.xn--cjs/"

new URL("ws://domain域.域").toString();
// => "ws://xn--domain-u21k.xn--cjs/"

new URL("file://domain域.域").toString();
// => "file://xn--domain-u21k.xn--cjs/"

new URL("ftp://domain域.域").toString();
// => "ftp://xn--domain-u21k.xn--cjs/"

new URL("git://domain域.域").toString();
// => "git://domain%E5%9F%9F.%E5%9F%9F"

encodeURIComponent

encodeURIComponent 遵循 RFC2396，

reserved    = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
            "$" | ","

unreserved  = alphanum | mark

mark        = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"

而非 RFC3986。

reserved    = gen-delims / sub-delims

gen-delims  = ":" / "/" / "?" / "#" / "[" / "]" / "@"

sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
            / "*" / "+" / "," / ";" / "="

unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"

因为 RFC3986 支持了 IPv6。

在 encodeURIComponent 中，大小写、数字和 -_.!~*'() 不会被转义，即： abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.!~*'() 不会被转义。

要支持 RFC3986，还需要转义 !'()*。
要支持 RFC5987，还需要转义 ['()*]，无需转义 |`^，（用于 Content-Disposition 和 Link 标头）

function encodeRFC3986URIComponent(str) {
    return encodeURIComponent(str).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
}

function encodeRFC5987ValueChars(str) {
    return encodeURIComponent(str)
        .replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
        .replace(/%(7C|60|5E)/g, (str, hex) => String.fromCharCode(parseInt(hex, 16)));
}

下为 engine262 实现：

const uriReserved = ";/?:@&=+$,";
const uriAlpha = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
const uriMark = "-_.!~*'()";
const DecimalDigit = "0123456789";
const uriUnescaped = uriAlpha + DecimalDigit + uriMark;

/** https://tc39.es/ecma262/#sec-encodeuricomponent-uricomponent */
function* encodeURIComponent([uriComponent = Value.undefined]: Arguments): ValueEvaluator {
    // 1. Let componentString be ? ToString(uriComponent).
    const componentString = Q(yield* ToString(uriComponent));
    // 2. Let unescapedURIComponentSet be a String containing one instance of each code unit valid in uriUnescaped.
    const unescapedURIComponentSet = uriUnescaped;
    // 3. Return ? Encode(componentString, unescapedURIComponentSet).
    return Q(Encode(componentString, unescapedURIComponentSet));
}

/** https://tc39.es/ecma262/#sec-encodeuri-uri */
function* encodeURI([uri = Value.undefined]: Arguments): ValueEvaluator {
    // 1. Let uriString be ? ToString(uri).
    const uriString = Q(yield* ToString(uri));
    // 2. Let unescapedURISet be a String containing one instance of each code unit valid in uriReserved and uriUnescaped plus "#".
    const unescapedURISet = `${uriReserved}${uriUnescaped}#`;
    // 3. Return ? Encode(uriString, unescapedURISet).
    return Q(Encode(uriString, unescapedURISet));
}

不难看出，encodeURI 除了不会转义 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.!~*'() 以外，还不会转义 ;/?:@&=+$,#。

下为 quickjs 实现：

static JSValue js_global_encodeURI(JSContext *ctx, JSValueConst this_val,
                                   int argc, JSValueConst *argv,
                                   int isComponent)
{
    JSValue str;
    StringBuffer b_s, *b = &b_s;
    JSString *p;
    int k, c, c1;

    str = JS_ToString(ctx, argv[0]);
    if (JS_IsException(str))
        return str;

    p = JS_VALUE_GET_STRING(str);
    string_buffer_init(ctx, b, p->len);
    for (k = 0; k < p->len;) {
        c = string_get(p, k);
        k++;
        if (isURIUnescaped(c, isComponent)) {
            string_buffer_putc16(b, c);
        } else {
            if (is_lo_surrogate(c)) {
                js_throw_URIError(ctx, "invalid character");
                goto fail;
            } else if (is_hi_surrogate(c)) {
                if (k >= p->len) {
                    js_throw_URIError(ctx, "expecting surrogate pair");
                    goto fail;
                }
                c1 = string_get(p, k);
                k++;
                if (!is_lo_surrogate(c1)) {
                    js_throw_URIError(ctx, "expecting surrogate pair");
                    goto fail;
                }
                c = from_surrogate(c, c1);
            }
            if (c < 0x80) {
                encodeURI_hex(b, c);
            } else {
                /* XXX: use C UTF-8 conversion ? */
                if (c < 0x800) {
                    encodeURI_hex(b, (c >> 6) | 0xc0);
                } else {
                    if (c < 0x10000) {
                        encodeURI_hex(b, (c >> 12) | 0xe0);
                    } else {
                        encodeURI_hex(b, (c >> 18) | 0xf0);
                        encodeURI_hex(b, ((c >> 12) & 0x3f) | 0x80);
                    }
                    encodeURI_hex(b, ((c >> 6) & 0x3f) | 0x80);
                }
                encodeURI_hex(b, (c & 0x3f) | 0x80);
            }
        }
    }
    JS_FreeValue(ctx, str);
    return string_buffer_end(b);

fail:
    JS_FreeValue(ctx, str);
    string_buffer_free(b);
    return JS_EXCEPTION;
}

URLSearchParams

RFC1866 和 HTML 标准均定义过 application/x-www-form-urlencoded。

URLSearchParams.prototype.toString() 遵循 application/x-www-form-urlencoded。
在 URLSearchParams 中，空格会被编码为 + 而不是 %20。

大小写、数字和 -_.* 不会被转义，空格被编码为 +，其余字符按百分号编码。

总结

规范	不编码字符
RFC2396	`abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.!~*'()`
RFC3986	`abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.~`
application/x-www-form-urlencoded	`abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.*`

const encodeQueryParam = (s) => new URLSearchParams({ "": s }).toString().slice(1);

encodeQueryParam("~"); // => %7E

// decodeURIComponent 会解码所有百分号编码串，但是注意查询字符串中空格会被编码为加号
const decodeQueryParam = (s) => decodeURIComponent(s.replace(/\+/g, " "));

decodeQueryParam("%7E"); // => ~

←Back to home

This work is licensed under CC BY-NC-SA 4.0