JavaScriptURLAPI使用教程

JavaScript 的 URL API 是现代浏览器和 Node.js（v10.0+）原生内置的标准化 URL 解析与构建工具，无需引入第三方库即可安全、可靠地拆解和组装 URL；它要求传入绝对 URL 或配合 base 参数使用，所有属性均为只读，query 操作必须通过 URLSearchParams 实现自动编解码，路径或协议变更需新建实例，同时对不可信输入务必用 try/catch 防御并校验协议合法性——掌握这些核心规则，能帮你彻底告别脆弱的手动字符串处理和正则解析，写出更健壮、可维护的 URL 相关代码。

URL API 是浏览器原生支持的 URL 解析工具，不是第三方库

它从 ES2015（ES6）起就内置在现代浏览器中，无需 import 或安装。Node.js 从 v10.0.0 开始也支持（需注意版本），但早期版本或某些运行时（如 Deno、某些打包环境）可能不完全兼容。它的核心价值是：用标准、可靠、无正则风险的方式拆解和组装 URL。

new URL() 构造函数必须传入完整 URL 字符串

常见错误是直接传入相对路径或不带协议的字符串，比如 new URL("/api/user?id=1") 会抛出 TypeError: Invalid URL。它需要一个可解析的绝对 URL，或配合 base 参数使用：

• ✅ 正确：new URL("https://example.com/api/user?id=1")
• ✅ 正确（带 base）：new URL("/api/user?id=1", "https://example.com")
• ❌ 错误：new URL("/api/user?id=1")（缺少 base，报错）
• ❌ 错误：new URL("api/user")（既不绝对也不合法相对）

构造后返回的对象有多个只读属性：href、origin、protocol、username、password、hostname、port、pathname、search、hash —— 这些都是字符串，不能直接赋值修改。

URLSearchParams 处理 query string 最安全

search 属性只是字符串（如 "?a=1&b=2"），真正解析和操作参数要用 URLSearchParams。它比手写正则或 split("&") 更健壮，自动处理编码/解码：

const url = new URL("https://example.com/?name=%E4%BD%A0%E5%A5%BD&city=Shanghai");
const params = url.searchParams;

console.log(params.get("name")); // "你好"
console.log(params.has("city")); // true
params.set("age", "25");
params.append("tag", "js");
console.log(url.href); // "https://example.com/?name=%E4%BD%A0%E5%A5%BD&city=Shanghai&age=25&tag=js"

注意：url.searchParams 是实时绑定的 —— 修改它会自动更新 url.href 和 url.search；但它不响应式更新原始字符串变量，只影响该 URL 实例。

修改 URL 要靠重新赋值，不是直接改属性

URL 对象的属性全是只读的，想改路径、协议或参数，必须通过 searchParams 或拼接新字符串再构造新实例：

• 改 query：用 url.searchParams.set() 等方法（推荐）
• 改 pathname：只能新建实例，如 new URL("/new/path" + url.search, url.origin)
• 改 protocol/host：同上，new URL(url.toString().replace(/^http:/, "https:")) 不可靠，应显式重组

别试图写 url.pathname = "/new" —— 这不会生效，也不会报错，只是静默忽略。

真正容易被忽略的是：URL API 不处理 URL 编码异常（比如未闭合的 %XX）、不校验域名格式、也不做网络请求验证。它只做结构解析。如果你拿到的 URL 来自用户输入或不可信来源，先 try/catch 包裹 new URL()，再检查 url.protocol 是否为 "http:" 或 "https:"，避免 javascript: 或 data: 类型引发意外行为。

今天关于《JavaScriptURLAPI使用教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！