Node.js 中的 URL 模块

一、URL 模块基础

1. 模块导入方式

// Node.js 方式
const url = require('url');// ES 模块方式 (Node.js 14+ 或启用 ESM)
import * as url from 'url';

2. 核心功能

• 解析 URL 字符串

• 格式化 URL 对象

• URL 处理工具方法

• WHATWG URL 标准实现

二、URL 解析与构建

1. 传统解析方法 (Legacy API)

const urlObj = url.parse('https://example.com:8080/p/a/t/h?query=string#hash');// 解析结果示例
{protocol: 'https:',slashes: true,auth: null,host: 'example.com:8080',port: '8080',hostname: 'example.com',hash: '#hash',search: '?query=string',query: 'query=string',pathname: '/p/a/t/h',path: '/p/a/t/h?query=string',href: 'https://example.com:8080/p/a/t/h?query=string#hash'
}

参数解析模式

const urlObj = url.parse('https://example.com?foo=bar&abc=xyz', true);
// urlObj.query 结果为 { foo: 'bar', abc: 'xyz' }

2. WHATWG URL API (推荐)

const myURL = new URL('https://example.com:8080/p/a/t/h?query=string#hash');// URL 对象属性
console.log(myURL.href);        // 完整URL
console.log(myURL.protocol);    // 'https:'
console.log(myURL.hostname);    // 'example.com'
console.log(myURL.port);        // '8080'
console.log(myURL.pathname);    // '/p/a/t/h'
console.log(myURL.search);      // '?query=string'
console.log(myURL.hash);        // '#hash'
console.log(myURL.origin);      // 'https://example.com:8080'

查询参数处理

const myURL = new URL('https://example.com/?user=abc&query=xyz');// 获取查询参数
console.log(myURL.searchParams.get('user')); // 'abc'// 设置查询参数
myURL.searchParams.set('page', '1');
console.log(myURL.href); 
// 'https://example.com/?user=abc&query=xyz&page=1'// 遍历参数
myURL.searchParams.forEach((value, name) => {console.log(`${name}: ${value}`);
});

三、URL 格式化与操作

1. 格式化 URL 对象

// 传统方式
const formattedUrl = url.format({protocol: 'https',hostname: 'example.com',pathname: '/some/path',query: { page: 1, limit: 10 }
});
// 'https://example.com/some/path?page=1&limit=10'// WHATWG 方式
const myURL = new URL('https://example.com');
myURL.pathname = '/new/path';
myURL.search = '?filter=latest';
console.log(myURL.href); 
// 'https://example.com/new/path?filter=latest'

2. URL 拼接

// 传统方式
const resolvedUrl = url.resolve('https://example.com/foo/bar', '../baz');
// 'https://example.com/baz'// WHATWG 方式
const baseUrl = new URL('https://example.com/foo/bar');
const newUrl = new URL('../baz', baseUrl);
console.log(newUrl.href); 
// 'https://example.com/baz'

四、URLSearchParams 类

1. 基本用法

const params = new URLSearchParams('key1=value1&key2=value2');// 添加参数
params.append('key3', 'value3');// 获取参数
console.log(params.get('key1')); // 'value1'// 检查存在
console.log(params.has('key2')); // true// 删除参数
params.delete('key2');// 转换为字符串
console.log(params.toString()); // 'key1=value1&key3=value3'

2. 高级操作

const params = new URLSearchParams([['user', 'abc'],['query', 'first'],['query', 'second']
]);// 获取所有值
console.log(params.getAll('query')); // ['first', 'second']// 迭代参数
for (const [name, value] of params) {console.log(`${name}: ${value}`);
}// 排序参数
params.sort();

五、实际应用场景

1. Web 服务器路由解析

const http = require('http');
const url = require('url');http.createServer((req, res) => {const parsedUrl = url.parse(req.url, true);// 获取路径和查询参数const pathname = parsedUrl.pathname;const query = parsedUrl.query;if (pathname === '/search' && query.q) {// 处理搜索请求}
}).listen(3000);

2. 构建 API 端点

function buildApiUrl(base, endpoint, params) {const apiUrl = new URL(endpoint, base);Object.entries(params).forEach(([key, value]) => {apiUrl.searchParams.append(key, value);});return apiUrl.href;
}const url = buildApiUrl('https://api.example.com', '/v1/products', {category: 'electronics',page: 2,limit: 20
});

3. 安全重定向验证

function safeRedirect(baseUrl, redirectPath) {try {const redirectUrl = new URL(redirectPath, baseUrl);// 验证是否同源if (redirectUrl.origin === new URL(baseUrl).origin) {return redirectUrl.href;}return baseUrl;} catch (e) {return baseUrl;}
}

六、注意事项与最佳实践

1. 安全性考虑

• 始终验证用户提供的 URL

• 处理 URL 解析错误

• 警惕协议跳转 (http → https)

• 注意编码问题 (防止 XSS)

2. 性能建议

• 重用 URL 和 URLSearchParams 对象

• 避免频繁解析相同 URL

• 对大量参数使用 URLSearchParams 而不是字符串操作

3. 兼容性说明

• 传统 API (url.parse()) 已弃用但仍在维护

• WHATWG URL API 是现代标准实现

• Node.js 10+ 完全支持 WHATWG URL

七、常见问题解决方案

1. 处理特殊字符

const myURL = new URL('https://example.com');
myURL.searchParams.set('query', 'some value with spaces');
console.log(myURL.href); 
// 'https://example.com/?query=some+value+with+spaces'

2. 获取不带查询的路径

const myURL = new URL('https://example.com/path?query=string');
console.log(myURL.pathname + myURL.hash); // '/path'

3. 比较 URL

function areUrlsEqual(url1, url2) {try {return new URL(url1).href === new URL(url2).href;} catch (e) {return false;}
}

URL 模块是 Node.js 中处理 Web 地址的核心工具，熟练掌握可以高效解决各种 URL 操作需求。WHATWG URL API 提供了更现代、更符合标准的实现方式，推荐在新项目中使用。