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

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

2025-06-21 17:41:23作者:龚格成

背景介绍

在医疗影像领域,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_URLrouterBasename 完全一致
  2. 对于生产环境,建议使用 CI/CD 流程自动化这些配置
  3. 在 Windows 环境下开发时,注意环境变量设置的语法差异
  4. 部署前先在本地测试自定义路径的访问

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

登录后查看全文
热门项目推荐
相关项目推荐