Unlighthouse静态报告构建中的路径问题解决方案

在Unlighthouse项目中构建静态报告时，开发者可能会遇到路径引用问题。本文将深入分析该问题并提供专业解决方案。

问题背景

当使用Unlighthouse的--build-static命令生成静态报告时，系统默认会创建绝对路径引用。例如，生成的index.html文件中会包含类似/assets/index.12341234.js这样的绝对路径引用。

这种设计在简单的部署场景下工作良好，但在某些特定部署架构中会带来问题。特别是当需要将多个扫描结果集中部署到同一个Web服务器下的不同子目录时，绝对路径会导致资源加载失败。

典型问题场景

假设我们有以下部署需求：

• 主域名下托管多个扫描结果
• 每个扫描结果位于不同的子目录
• 使用S3或CloudFront+S3作为托管平台

目录结构示例：

domain.com/site1-scan1/
domain.com/site2-scan1/
domain.com/site2-scan2/

在这种结构下，浏览器会尝试从根目录加载资源（如domain.com/assets/），而实际资源位于子目录中（如domain.com/site1-scan1/assets/），导致404错误。

解决方案

Unlighthouse提供了routerPrefix配置项来解决这一问题。该配置项可以在以下两种方式中使用：

1. 通过配置文件： 在Unlighthouse配置文件中设置routerPrefix为所需的路径前缀。

2. 通过命令行参数： 使用--router-prefix命令行参数指定路径前缀。

实现建议

对于需要部署到子目录的场景，建议：

1. 在构建时明确指定routerPrefix为子目录路径
2. 确保部署后的目录结构与指定的前缀匹配
3. 对于自动化部署流程，可以通过环境变量动态设置前缀

注意事项

虽然可以通过手动修改生成文件中的路径来解决问题，但这种做法存在潜在风险：

• 可能意外修改报告内容中的合法路径
• 增加了维护复杂性
• 不是官方支持的解决方案

相比之下，使用routerPrefix配置是更可靠、更安全的解决方案，也是官方推荐的做法。

通过正确使用这一配置，开发者可以灵活地将Unlighthouse生成的静态报告部署到各种复杂的Web架构中，而无需担心资源加载问题。