如何构建可在域名cms子目录下运行的React应用

1. 构建工具基础路径配置 #

基于 Create React App（CRA）创建的项目 #

• 方法一（未eject）：直接在项目根目录的package.json文件中新增字段：

  "homepage": "/cms/"
  

• 方法二（已eject/自定义webpack配置）：修改webpack配置中output的publicPath属性为'/cms/'

基于 Vite 创建的项目 #

修改项目根目录的vite.config.js或vite.config.ts，在导出的配置中新增base字段：

export default defineConfig({
  base: '/cms/',
  // 其他原有配置保持不变
})

2. 路由配置 #

如果项目使用react-router做路由管理，需要给路由组件添加basename属性：

HashRouter 模式 #

import { HashRouter } from 'react-router-dom'

<HashRouter basename="/cms">
  {/* 原有路由规则、App组件等内容保持不变 */}
</HashRouter>

BrowserRouter 模式 #

除了添加basename属性外，还需要额外配置服务端重定向规则，避免刷新页面出现404：

import { BrowserRouter } from 'react-router-dom'

<BrowserRouter basename="/cms">
  {/* 原有路由规则、App组件等内容保持不变 */}
</BrowserRouter>

常用Nginx服务端配置参考：

location /cms {
  alias /你服务器上项目cms目录的绝对路径;
  index index.html index.htm;
  try_files $uri $uri/ /cms/index.html;
}

3. 静态资源引用注意事项 #

• 引用public目录下的静态资源时，不要写死绝对路径，使用构建工具提供的环境变量拼接：
  • CRA 项目：${process.env.PUBLIC_URL}/资源路径，例：<img src={${process.env.PUBLIC_URL}/logo.png} alt="logo" />
  • Vite 项目：${import.meta.env.BASE_URL}/资源路径，例：<img src={${import.meta.env.BASE_URL}/logo.png} alt="logo" />
• 样式文件中用相对路径引用的本地资源无需额外修改，构建工具会自动补全路径前缀

4. 打包与部署 #

1. 执行常规打包命令：npm run build
2. 将打包生成的dist文件夹内的所有文件，上传到服务器域名根目录下的cms子文件夹中
3. 直接访问https://domainname.co.ug/cms/即可正常使用应用

内容的提问来源于stack exchange，提问作者Akampurira Brian David