OHIF Viewer在非根路径部署时的配置解决方案

背景介绍

OHIF Viewer是一个开源的医学影像查看器，广泛应用于医疗影像领域。在实际部署过程中，开发者经常需要将OHIF Viewer集成到现有系统中，而非作为独立应用部署在根路径下。这种情况下，正确的配置对于确保应用正常运行至关重要。

问题现象

当开发者尝试将OHIF Viewer部署在非根路径时（例如/med/study-images/ohif/），可能会遇到应用无法加载的问题。具体表现为：

1. 主页面加载成功（返回200状态码）
2. 但后续资源请求（如app-config、JS包和静态资源）未能正确发起
3. 应用界面显示为空白

根本原因分析

这个问题通常源于两个关键配置项未正确设置：

1. PUBLIC_URL：构建时指定的公共路径前缀
2. routerBasename：运行时路由的基础路径

当这些配置与实际的部署路径不匹配时，浏览器无法正确解析资源路径，导致资源加载失败。

解决方案

1. 构建配置调整

在项目构建前，需要确保PUBLIC_URL环境变量正确设置为目标部署路径。例如，如果计划部署到/med/study-images/ohif/路径下：

PUBLIC_URL=/med/study-images/ohif/ npm run build

或者在platform/app/package.json中修改构建脚本：

"scripts": {
  "build": "PUBLIC_URL=/med/study-images/ohif/ webpack --mode production"
}

2. 运行时配置调整

在应用配置文件中（通常位于platform/app/public/config/目录下），需要设置匹配的routerBasename：

window.config = {
  routerBasename: '/med/study-images/ohif',
  // 其他配置项...
};

3. 路径匹配原则

• PUBLIC_URL必须以斜杠结尾（/）
• routerBasename不应以斜杠结尾
• 两者应保持相同的路径前缀

最佳实践建议

1. 测试环境验证：先在本地或测试环境验证配置，确认无误后再部署到生产环境
2. 路径规范化：确保所有路径配置使用一致的格式（避免混用相对路径和绝对路径）
3. 构建产物检查：构建完成后，检查生成的index.html文件中的资源引用路径是否正确
4. 反向代理配置：如果使用Nginx等反向代理，确保代理规则不会影响路径解析

常见误区

1. 路径深度不一致：PUBLIC_URL和routerBasename设置的路径深度不同
2. 斜杠使用不当：路径结尾是否包含斜杠会影响路由匹配
3. 环境变量覆盖：构建时环境变量可能被其他配置文件覆盖
4. 缓存问题：浏览器可能缓存了错误的资源路径

通过正确理解OHIF Viewer的路径解析机制，并按照上述方案进行配置，可以确保应用在各种部署场景下都能正常加载和运行。