JavaScript URL 与查询字符串：URL 和 URLSearchParams

别再用字符串技巧解析 URL 了

在 URL API 出现之前，人们用 split('?')、正则表达式和运气来切分 URL。大部分时候能用，直到某个值里出现了 &、=、空格或者非 ASCII 字符，就不行了。浏览器和 Node 都自带了一个正规的解析器，用它就好。

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

一次调用，URL 的每个部分都已经拆分好并正确解码。遇到无效输入时，构造函数会抛出 TypeError，这通常正是你想要的：一个乱七八糟的 URL 应该大声报错，而不是悄悄在下游产生乱七八糟的结果。

读取查询参数

每个 URL 都有一个 .searchParams 属性，它是一个 URLSearchParams 对象，知道如何读写查询字符串：

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

有几点值得注意：

• 返回的值已经解码。?name=Ada%20Lovelace 得到的是 "Ada Lovelace"。
• 所有值都是字符串。"2" 不是 2。需要数字时用 Number() 转换。
• 键可以重复出现。get 返回第一个匹配的值；getAll 返回所有匹配的值。
• 不存在的键返回 null 而不是 undefined，所以和 ?? "default" 搭配很好用。

构建查询字符串

你可以用 URLSearchParams 从零开始构建查询字符串，不用手动转义，也不用自己用 & 连接：

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

也可以从一个对象构建：任何由 [key, value] 对组成的可迭代对象都可以，普通对象也行：

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set 与 append 的区别：set 会替换该键已有的值，append 会再添加一个。当一个键本来就可以重复时（标签、筛选条件）用 append；单值参数用 set。

修改 URL

因为 URL 是一个实时联动的对象，修改 searchParams 会自动更新 .search 和 .href：

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // overwrites
u.searchParams.delete("utm_source");       // no-op if absent

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

这是给已有 URL 追加查询参数的惯用写法。不用检查“URL 里是否已经有 ?”，也不用操心该加 & 还是 ?。

你也可以用同样的方式修改 URL 的其他部分：

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

遍历参数

URLSearchParams 是可迭代的。for...of 会给你 [key, value] 对，另外还有常见的 keys()、values() 和 entries() 辅助方法：

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

注意，重复的键会出现多次：你会看到 tag = web，然后是 tag = beginner，作为两个独立的条目。这忠实地反映了实际的查询字符串。

如果你想得到一个普通对象，方便调试时打印，可以用 Object.fromEntries，但它会合并重复的键，只保留最后一个值：

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

调试时没问题。如果有键可能重复，就不对了。

相对 URL 需要一个基础 URL

单独调用 new URL("/search?q=js") 会抛出错误，因为相对路径本身不是一个有效的 URL。把基础 URL 作为第二个参数传进去：

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

解析规则和浏览器处理 <a href> 的规则一样：以 / 开头表示从主机根目录开始的绝对路径，不带斜杠表示相对于当前路径，.. 表示向上一级。当你根据配置好的基础地址拼装 API URL 时，这非常方便。

在浏览器中，window.location.href 就是现成的基础 URL，可以用来解析当前页面的 URL：

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

处理无效的 URL

URL 构造函数遇到格式错误的输入会抛出错误。这很有用，但也意味着解析用户输入或外部系统发来的任何内容时，都需要 try/catch：

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL object
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

现代环境还提供了 URL.canParse(input)，它返回一个布尔值。如果你只是想做校验，就不必写那一套 try/catch：

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

一个可运行的小例子

把这些组合起来：从 URL 中读取当前的筛选条件，修改它们，然后生成一个可以跳转的新 URL：

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

传入 null 会删除该参数，传入其他任何值则会设置或覆盖它。每当你构建筛选界面、分页或深层链接时，最终都会以某种形式写出这种模式。

要点总结

• new URL(string) 把 URL 解析成带标签的各个部分，遇到无效输入会抛出错误。
• url.searchParams 是一个 URLSearchParams，使用 get、getAll、set、append、delete、has。
• 编码会自动完成。除非你在手动拼接字符串，否则不需要 encodeURIComponent。
• 把基础 URL 作为第二个参数传入，就能解析相对路径。
• 对于不可信的输入，URL.canParse（或 try/catch）就是你的校验工具。

每当你想用 .split('?') 切分 URL，或者用正则表达式提取查询参数时，请改用这些 API。它们更简洁、更正确，而且运行环境已经自带。