本教程旨在解决在jenkins环境中，html页面通过iframe嵌入团队报告时，因web服务器对相对路径解析不当而导致的404错误。文章深入分析了问题根源，并提供了采用完全限定url（绝对路径）作为解决方案，同时探讨了jenkins报告发布的最佳实践，以确保资源正确加载并提升系统稳定性。
问题背景与现象
在持续集成/持续部署（CI/CD）流程中，我们常会遇到需要整合不同报告或视图的需求。一个典型场景是，团队的Jenkins工具生成了多个HTML格式的硬件仿真测试报告（例如Session_20Data_20for_20Overview_20Report/index.html和Runs_20Data_20for_20Overview_20Report/index.html）。为了方便团队成员在一个页面中集中查看这些报告，通常会创建一个父级HTML页面（如overview.html），并利用
初始的overview.html结构可能如下所示，其中src属性使用了相对路径：
回归报告
这种设置在某些环境下（例如直接在文件系统上打开overview.html，或在特定的Linux环境）可能工作正常。然而，在某些情况下（例如在Windows环境，或通过Jenkins的内置Web服务器提供服务时），Iframe区域却无法正常显示内容，而是抛出HTTP ERROR 404 Not Found错误，具体的URI路径显示为/static-files/Session_20Data_20for_20Overview_20Report/index.html等。尽管文件结构和相对路径看似正确，但服务器端却无法找到这些资源。
404错误根源分析
这个404错误的核心在于Web服务器（在本例中，Jenkins通常使用内置的Jetty服务器和Stapler Servlet来提供服务）如何解析和处理HTML页面中的相对路径。
立即学习“前端免费学习笔记（深入）”；
文件系统与Web服务器的路径解析差异： 当您直接在浏览器中打开本地文件系统中的overview.html时（例如file:///C:/path/to/Overview/overview.html），浏览器会根据overview.html的物理位置来解析../这样的相对路径，从而准确找到同级目录下的报告文件。 然而，当overview.html通过Web服务器（如Jenkins）提供服务时，浏览器请求的是一个URL（例如http://your-jenkins-instance/job/your-job/ws/Overview/overview.html）。此时，
服务器的静态资源映射： 错误信息中出现的URI: /static-files/Session_20Data_20for_20Overview_20Report/index.html以及SERVLET: Stapler和Powered by Jetty，强烈暗示Jenkins的Web服务器在尝试解析这些相对路径时，可能将其映射到了一个预设的静态文件服务路径或上下文根。/static-files/前缀表明服务器尝试从其内部配置的静态资源目录中查找这些文件，而不是从Jenkins工作区的相对路径中。由于报告文件并未被Jenkins配置为从/static-files/路径下提供，因此导致了404错误。
简而言之，问题出在服务器端对overview.html中
解决方案：采用完全限定URL
解决此类问题的最直接和最可靠的方法是，将
原理： 完全限定URL明确指定了资源的精确网络位置，它不依赖于当前页面的URL或服务器的路径解析逻辑。无论父页面在何处被提供，浏览器都能直接通过这个完整的URL向服务器请求资源，从而避免了相对路径可能带来的歧义和解析错误。
如何获取完全限定URL：
- 在Jenkins中，找到并直接导航到您想要嵌入的报告页面。例如，找到Jenkins工作区中生成的Session_20Data_20for_20Overview_20Report/index.html。
- 在浏览器中打开这个报告文件。
- 复制浏览器地址栏中显示的完整URL。这个URL通常会包含Jenkins实例的地址、任务名称、工作区路径等信息，例如： http://your-jenkins-instance:port/job/your-job-name/ws/Session_20Data_20for_20Overview_20Report/index.html 或 http://your-jenkins-instance:port/jenkins/job/your-job-name/ws/Session_20Data_20for_20Overview_20Report/index.html (如果Jenkins部署在/jenkins上下文路径下)
示例代码：
将overview.html中的
回归报告
重要提示： 请务必将示例中的http://your-jenkins-instance:port/job/your-job-name/ws/替换为您的Jenkins实例的实际URL前缀。
Jenkins报告的最佳实践与注意事项
除了使用完全限定URL解决当前问题外，还有一些关于在Jenkins中处理报告的最佳实践和注意事项值得关注：
跨域安全警告 (CORS)： 在原始问题描述中提到了一个警告：“Due to Cross Origin Request Security(CORS), this browsing mode is now deprecated.”。虽然CORS不是导致404错误的直接原因（404是资源未找到，CORS是找到但拒绝访问），但它是一个重要的安全考虑。如果您的Iframe内容（报告）和父页面（overview.html）最终被部署在不同的域名、端口或协议下，浏览器可能会因为CORS策略而阻止Iframe内容的加载。使用完全限定URL时，如果URL指向的资源与父页面同源，则通常不会遇到CORS问题。如果不同源，则需要服务器端（Jenkins）配置CORS头来允许跨域访问。
-
利用Jenkins的HTML Publisher Plugin： Jenkins官方推荐的做法是使用插件来发布HTML报告，例如HTML Publisher Plugin。这个插件允许您指定Jenkins作业生成的HTML报告的路径，然后Jenkins会自动将这些报告发布为作业构建结果的一部分。通过这种方式发布的报告，Jenkins会负责正确地提供这些文件，并生成稳定的、可访问的URL。这不仅能解决路径解析问题，还能更好地集成到Jenkins的UI中，并可能提供更好的安全控制。
-
优点：
- Jenkins负责路径解析，避免手动处理URL。
- 报告与构建结果关联，便于追踪。
- 可能提供更好的安全性和访问控制。
- 符合Jenkins的推荐实践，避免“浏览模式已弃用”的警告。
使用方法概述： 在Jenkins作业配置的“构建后操作”中，添加“Publish HTML reports”，然后指定HTML报告的目录和入口文件（例如index.html）。插件会自动生成一个指向这些报告的链接。
-
动态URL管理： 如果您的Jenkins任务名称、实例地址或工作区路径经常变化，硬编码完全限定URL可能不够灵活。在这种情况下，可以考虑在生成overview.html时，利用Jenkins的环境变量（如BUILD_URL, JOB_URL, WORKSPACE等）来动态构建Iframe的src属性。例如，在Groovy脚本或Shell脚本中生成HTML内容时，可以插入这些变量。
总结
在Web服务器环境下（尤其是像Jenkins这样的CI/CD工具），理解路径解析机制至关重要。当
更进一步，对于Jenkins环境中的HTML报告，强烈建议利用HTML Publisher Plugin等官方推荐的工具来发布和管理报告。这不仅能解决当前的路径问题，还能提供更稳定、安全和集成的报告查看体验，符合现代Web开发的最佳实践。
