本文探讨了在复杂部署环境中（如ReadTheDocs或CI/CD工具）识别网站真实根路径的挑战。由于`window.location.origin`可能无法准确反映带有语言或版本前缀的有效根目录，文章提出并详细阐述了如何利用`fetch` API的重定向跟踪功能，通过发出`HEAD`请求来动态获取网站的实际有效根URL，从而正确构建绝对路径。
理解网站根路径的挑战
在Web开发中，尤其是在构建文档版本切换器或处理重定向逻辑时，准确识别一个网站的“根路径”至关重要。通常，开发者会倾向于使用window.location.origin来获取当前页面的协议、域名和端口，并将其作为网站的根。例如，对于https://example.com/docs/page.html，window.location.origin会返回https://example.com。
然而，在某些特定的部署场景下，如使用ReadTheDocs（RDT）这样的第三方文档构建服务或在CI/CD环境中进行预览部署时，window.location.origin可能无法代表网站的“有效”根目录。例如，一个RDT构建的文档可能其主页是https://pydata-sphinx-theme.readthedocs.io/en/stable/，而非简单的https://pydata-sphinx-theme.readthedocs.io。同样，一个PR预览构建的URL可能是https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/，而不是https://pydata-sphinx-theme--1344.org.readthedocs.build。
在这种情况下，如果用户尝试访问一个在旧版本中不存在的页面（例如，从https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/index.html切换到v0.9，而该页面在v0.9中不存在），我们希望将其重定向到该版本的有效根目录，例如https://pydata-sphinx-theme.readthedocs.io/en/v0.9.0/。如果仅依赖window.location.origin，则可能导致重定向到错误的或无效的路径。
初始尝试与局限性
为了将相对URL转换为绝对URL，一种常见的做法是结合window.location.origin：
/**
* 检查URL是否为绝对路径，如果不是，则从网站根目录生成绝对路径。
*
* @param {string} url 要检查的URL。
* @returns {string} 处理后的绝对URL。
*/
function makeAbsoluteUrl(url) {
// 正则表达式模式匹配相对URL
const pattern = /^(?!(?:[a-z]+:)?\/\/)/i;
const baseUrl = window.location.origin; // 初始尝试使用origin作为基准
url = pattern.test(url) ? baseUrl + "/" + url : url;
return url;
}然而，正如前面所述，当网站的实际根路径包含子目录（如/en/stable/或/en/1344/）时，这种方法就会失效。例如，如果当前页面是https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/some/page.html，window.location.origin会返回https://pydata-sphinx-theme--1344.org.readthedocs.build。如果此时我们尝试将相对路径new-version/index.html转换为绝对路径，会得到https://pydata-sphinx-theme--1344.org.readthedocs.build/new-version/index.html，这显然不是我们期望的在en/1344/下的路径。
利用 fetch API 跟踪重定向获取真实根路径
经过分析，我们发现许多这类平台（如ReadTheDocs）在访问其裸域名（例如https://pydata-sphinx-theme.readthedocs.io）时，会自动将其重定向到带有默认语言和版本前缀的实际根路径（例如https://pydata-sphinx-theme.readthedocs.io/en/stable/）。这一行为为我们提供了一个识别真实根路径的有效途径。
我们可以利用JavaScript的fetch API，向window.location.origin发起一个HEAD请求。HEAD请求只会获取响应头，而不会下载整个页面内容，这使其效率更高。更重要的是，fetch API在处理重定向时，其返回的Response对象的url属性会包含最终重定向后的URL。
下面是改进后的makeAbsoluteUrl函数实现：
/**
* 异步函数：解析网站的真实根URL（处理重定向），然后根据需要将输入URL转换为绝对路径。
*
* @param {string} url 要检查并可能转换为绝对路径的URL。
* @returns {Promise} 一个Promise，解析为最终的绝对URL。
*/
async function makeAbsoluteUrl(url) {
// 正则表达式模式匹配相对URL
const pattern = /^(?!(?:[a-z]+:)?\/\/)/i;
let effectiveBaseUrl = window.location.origin; // 默认使用origin作为基准
try {
// 尝试向origin发起HEAD请求，以跟踪任何重定向
// 这对于像ReadTheDocs这样的平台至关重要，它们的"origin"通常会重定向到
// 更具体的根路径（例如，/en/stable/）。
const response = await fetch(window.location.origin, {
method: "HEAD",
redirect: "follow" // 确保fetch会跟踪所有重定向
});
effectiveBaseUrl = response.url; // 获取重定向后的最终URL
} catch (error) {
console.warn("无法通过fetch确定有效的基准URL，回退到window.location.origin:", error);
// 如果fetch失败，effectiveBaseUrl将保持为window.location.origin
}
// 如果输入URL是相对路径，则在其前面加上有效的基准URL
if (pattern.test(url)) {
// 确保在拼接时不会出现双斜杠，如果effectiveBaseUrl已经以斜杠结尾
const separator = effectiveBaseUrl.endsWith('/') ? '' : '/';
return effectiveBaseUrl + separator + url;
}
return url; // 如果URL已经是绝对路径，则直接返回
}
// 示例用法：
// 当页面在 https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/some/page.html 时
// makeAbsoluteUrl("new-version/index.html").then(absolutePath => {
// console.log(absolutePath); // 预期输出: https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/new-version/index.html
// });
// makeAbsoluteUrl("/en/v0.9.0/").then(absolutePath => {
// console.log(absolutePath); // 预期输出: https://pydata-sphinx-theme--1344.org.readthedocs.build/en/v0.9.0/
// }); 代码解析与注意事项
- async 函数与 await： 由于fetch API是异步的，makeAbsoluteUrl函数必须声明为async，并使用await关键字等待fetch操作完成并获取响应。
-
fetch(window.location.origin, { method: "HEAD", redirect: "follow" })：
- window.location.origin：作为请求的目标URL，我们期望它能触发重定向。
- method: "HEAD"：指示只获取响应头，这比GET请求更高效，因为它不需要下载整个页面内容。
- redirect: "follow"：这是fetch的默认行为，但明确指定它确保fetch会自动跟踪所有HTTP重定向，直到达到最终的URL。
- response.url： 在fetch操作成功并跟踪完所有重定向后，response.url属性将包含最终的、重定向后的URL。这个URL就是我们所寻找的网站的有效根路径。
- 错误处理： 使用try...catch块来捕获fetch可能抛出的错误（例如，网络问题或CORS限制）。如果fetch失败，函数会回退到使用window.location.origin作为基准，并输出警告信息。
- 路径拼接： 在将相对URL与effectiveBaseUrl拼接时，我们添加了一个简单的逻辑来避免出现双斜杠（例如https://example.com//path），确保路径格式正确。
- 异步性处理： 由于makeAbsoluteUrl现在是一个异步函数，调用者需要使用.then()或await来处理其返回的Promise，以获取最终的绝对URL。
总结
通过利用fetch API的重定向跟踪能力，我们可以克服window.location.origin在特定部署环境中（如ReadTheDocs、CI/CD预览）的局限性，准确地识别网站的真实有效根路径。这种方法对于构建需要精确URL解析和重定向逻辑的Web应用（尤其是文档版本切换器）非常有效。然而，需要注意的是，此解决方案主要针对那些通过HTTP重定向将其“裸”域名指向更深层有效根路径的场景。对于没有这种重定向行为的网站，window.location.origin可能仍然是合适的选择，或者需要结合其他逻辑进行判断。
