本文探讨了在动态部署环境（如文档构建器或ci/cd工具）中，如何准确获取网站的真实根路径，尤其当它并非简单的域名根目录时。针对 `window.location.origin` 不足的场景，我们提出了一种利用 `fetch` api发送 `head` 请求并捕获重定向url的解决方案，从而有效识别出包含子路径的实际网站根目录，并提供了具体的javascript实现及使用注意事项。
理解网站根路径识别的挑战
在Web开发中，我们经常需要将相对URL转换为绝对URL。通常情况下，我们可能倾向于使用 window.location.origin 来作为网站的根路径。例如，对于 https://example.com/docs/page.html，window.location.origin 会返回 https://example.com。然而，在现代的部署实践中，尤其是在使用文档构建器（如sphinx结合ReadTheDocs）或CI/CD工具时，网站的“功能性”根路径可能并非域名本身，而是包含特定子路径的URL。
例如，一个文档网站可能在 https://pydata-sphinx-theme.readthedocs.io/en/stable/ 处提供服务，而不是直接在 https://pydata-sphinx-theme.readthedocs.io。在开发或测试分支上，URL可能更复杂，如 https://pydata-sphinx-theme–1344.org.readthedocs.build/en/1344/。在这种情况下，如果仅依赖 window.location.origin，我们将无法得到正确的基准路径来构建绝对URL，导致链接错误或重定向失败。
最初的尝试可能如下所示，它将相对URL与 window.location.origin 拼接：
/** * 检查URL是否为相对路径，并根据需要从origin构建绝对路径。 * * @param {string} url 要检查的URL * @returns {string} 绝对URL */ function makeAbsoluteUrlWithOrigin(url) { // 匹配非绝对URL的正则表达式 const pattern = /^(?!(?:[a-z]+:)?//)/i; const base_url = window.location.origin; // 这里的base_url可能不准确 if (pattern.test(url)) { // 确保拼接时路径规范化 const normalizedBase = base_url.endsWith('/') ? base_url.slice(0, -1) : base_url; const normalizedUrl = url.startsWith('/') ? url.slice(1) : url; return `${normalizedBase}/${normalizedUrl}`; } return url; } // 示例： // 当前页面URL: https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/examples/index.html // makeAbsoluteUrlWithOrigin("other-page.html") 会返回: // https://pydata-sphinx-theme--1344.org.readthedocs.build/other-page.html // 而期望的结果可能是: // https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/other-page.html
显然，这种方法在需要包含子路径作为根目录的场景下是不足的。
解决方案：利用HTTP重定向识别真实根路径
许多部署平台（如ReadTheDocs）有一个共同的特点：当你访问其裸域名或项目根URL（例如 https://pydata-sphinx-theme.readthedocs.io 或 https://pydata-sphinx-theme–1344.org.readthedocs.build）时，它会自动重定向到一个更具体的、包含版本或语言信息的路径（例如 https://pydata-sphinx-theme.readthedocs.io/en/stable/）。这个重定向后的URL正是我们需要的“真实”网站根路径。
我们可以利用 fetch API发送一个 HEAD 请求来捕获这个重定向行为。HEAD 请求只获取资源的头部信息，不会下载整个响应体，因此效率较高。fetch 响应对象中的 url 属性会包含最终的（经过所有重定向后的）URL。
下面是实现这一策略的javaScript代码：
/** * 异步获取当前网站的真实根路径，考虑了从origin到功能性基准路径的重定向。 * * @returns {promise<string>} 一个Promise，解析为真实的基准URL。 */ async function getTrueWebsiteRoot() { try { // 向当前页面的origin发送HEAD请求。 // response.url 将包含经过所有重定向后的最终URL。 const response = await fetch(window.location.origin, { method: "HEAD" }); return response.url; } catch (error) { console.error("获取真实网站根路径失败:", error); // 如果获取失败，回退到window.location.origin，但请注意这可能不是“真实”根路径 return window.location.origin; } } /** * 检查给定的URL是否为相对路径，如果是，则使用确定的真实网站根路径将其转换为绝对路径。 * * @param {string} url 要检查并可能转换为绝对路径的URL。 * @returns {Promise<string>} 一个Promise，解析为绝对URL。 */ async function makeAbsoluteUrl(url) { // 匹配非绝对URL的正则表达式（不以协议或双斜杠开头） const isRelativeUrl = /^(?!(?:[a-z]+:)?//)/i; if (isRelativeUrl.test(url)) { const base_url = await getTrueWebsiteRoot(); // 等待获取真实的基准URL // 规范化base_url和传入的url，确保拼接正确 const normalizedBase = base_url.endsWith('/') ? base_url.slice(0, -1) : base_url; const normalizedUrl = url.startsWith('/') ? url.slice(1) : url; return `${normalizedBase}/${normalizedUrl}`; } return url; // 已经是绝对URL }
代码解析与注意事项
-
getTrueWebsiteRoot() 函数：
- 这是一个 async 函数，因为它内部使用了 await 来等待 fetch 请求的完成。
- fetch(window.location.origin, { method: “HEAD” })：向当前页面的原始域名（例如 https://pydata-sphinx-theme–1344.org.readthedocs.build）发起一个 HEAD 请求。HEAD 请求是获取资源头部信息最有效的方式，它不会下载资源的主体内容，从而节省带宽和时间。
- response.url：这是 fetch 响应对象的一个关键属性。它返回的是最终的URL，即在经过所有HTTP重定向之后浏览器实际访问的URL。这正是我们寻找的“真实”网站根路径。
- try…catch 块：用于捕获网络错误或 fetch 请求失败的情况，并提供一个回退机制（虽然回退到 window.location.origin 可能不总是理想的，但在无法获取真实根路径时，这是一个合理的默认值）。
-
makeAbsoluteUrl() 函数：
- 同样是一个 async 函数，因为它需要 await getTrueWebsiteRoot() 的结果。
- isRelativeUrl 正则表达式：用于判断传入的 url 是否为相对路径。它检查URL是否不以协议（如 http:、https:）或双斜杠（//）开头。
- await getTrueWebsiteRoot()：在这里我们调用并等待 getTrueWebsiteRoot 函数返回真实的基准URL。
- URL规范化：normalizedBase 和 normalizedUrl 确保在拼接URL时，不会出现双斜杠（//）或缺少斜杠的情况，例如 https://base.com//path 或 https://base.compath。
- 如果 url 已经是绝对路径，则直接返回。
-
异步操作：
- 由于 fetch 是一个异步操作，getTrueWebsiteRoot 和 makeAbsoluteUrl 都返回 Promise。这意味着在调用 makeAbsoluteUrl 时，你需要使用 await 或 .then() 来处理其结果。
// 示例用法： async function exampleUsage() { const relativePath = "examples/index.html"; const absolutePath = await makeAbsoluteUrl(relativePath); console.log(`原始相对路径: ${relativePath}`); console.log(`转换后的绝对路径: ${absolutePath}`); // 假设当前页面是 https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/any-page.html // 期望输出: https://pydata-sphinx-theme--1344.org.readthedocs.build/en/1344/examples/index.html } exampleUsage();
总结
通过利用 fetch API的 HEAD 请求和其响应的 url 属性，我们可以有效地解决在动态部署环境中识别网站真实根路径的挑战。这种方法特别适用于那些通过HTTP重定向来指引用户到其功能性根目录的平台。虽然此方案在处理特定类型的部署环境（如ReadTheDocs）时表现出色，但在更通用的场景下，仍需根据具体网站的结构和服务器配置进行调整。在实际应用中，还应考虑网络请求的开销，并可能为频繁调用的场景添加缓存机制。