OHIF Viewer 项目中使用自定义 baseUrl 的部署指南

背景介绍

在医疗影像领域，OHIF Viewer 是一个广泛使用的开源医学影像查看器。在实际部署过程中，很多用户需要将 OHIF Viewer 部署在非根路径下（如 /ohif/ 或 /viewer/），这就涉及到 baseUrl 的配置问题。

核心问题分析

当开发者尝试将 OHIF Viewer 部署在自定义路径时，经常遇到以下典型问题：

1. 只有 index.html 文件能够从自定义路径访问
2. 其他静态资源（如 JS 文件）只能从根路径加载
3. 页面加载后显示空白
4. 浏览器控制台报错资源加载失败

这些问题主要源于 React 应用的构建配置和服务器路由设置不匹配。

解决方案详解

1. 环境变量配置

首先需要设置正确的环境变量：

PUBLIC_URL=/your-custom-path/
APP_CONFIG=config/default.js

这两个变量分别控制：

• PUBLIC_URL：告诉 webpack 构建时所有静态资源的前缀路径
• APP_CONFIG：指定应用的配置文件路径

2. 配置文件修改

在 config/default.js 中，需要确保 routerBasename 与 PUBLIC_URL 一致：

window: {
  routerBasename: '/your-custom-path',
  // 其他配置...
}

3. Docker 部署的特殊处理

对于 Docker 部署，需要额外注意以下几点：

Dockerfile 修改

ENV PUBLIC_URL /your-custom-path/
ENV APP_CONFIG config/default.js

# 构建后需要将输出目录复制到自定义路径下
COPY --from=builder /usr/src/app/platform/app/dist /usr/share/nginx/html/your-custom-path

Nginx 配置调整

修改 .docker/Viewer-v3.x/default.conf.template 文件：

location / {
    try_files $uri $uri/ /your-custom-path/index.html;
}

4. 本地开发环境测试

对于本地测试，可以使用 serve 工具并配置 serve.json：

{
  "public": "build",
  "rewrites": [
    { "source": "/your-custom-path/**", "destination": "/index.html" }
  ]
}

常见问题排查

1. 资源404错误：检查是否所有静态资源都带有正确的前缀路径
2. 空白页面：确认 routerBasename 配置是否正确
3. 路由失效：确保服务器配置了正确的重写规则
4. 构建失败：清理缓存后重新构建（使用 --no-cache 参数）

最佳实践建议

1. 保持 PUBLIC_URL 和 routerBasename 完全一致
2. 对于生产环境，建议使用 CI/CD 流程自动化这些配置
3. 在 Windows 环境下开发时，注意环境变量设置的语法差异
4. 部署前先在本地测试自定义路径的访问

通过以上配置，开发者可以成功将 OHIF Viewer 部署在任何自定义路径下，满足各种复杂的部署场景需求。