如何在NGINX上通过不同子目录部署多套多环境VueJS 3应用

1. Vue3 项目侧统一配置（所有环境、所有应用都需调整） #

1.1 构建工具配置 #

若使用vue-cli构建（配置文件为vue.config.js）

module.exports = {
  // 核心：publicPath与部署子路径完全匹配，通过环境变量动态适配不同环境
  publicPath: process.env.NODE_ENV === 'production' 
    ? process.env.VUE_APP_DEPLOY_PATH 
    : '/',
  // 其余原有配置保持不变
}

若使用Vite构建（配置文件为vite.config.js）

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  // 核心：base参数与部署子路径完全匹配，通过环境变量动态适配不同环境
  base: process.env.NODE_ENV === 'production' 
    ? process.env.VITE_DEPLOY_PATH 
    : '/',
  // 其余原有配置保持不变
})

1.2 路由配置（router/index.js） #

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  // 核心：history模式的base参数与项目publicPath完全一致
  history: createWebHistory(process.env.NODE_ENV === 'production' 
    ? process.env.VUE_APP_DEPLOY_PATH // Vite环境替换为import.meta.env.VITE_DEPLOY_PATH
    : '/'),
  routes: [
    // 原有路由规则保持不变
  ]
})

export default router

1.3 环境变量与打包命令配置 #

在项目根目录下新建3个环境变量文件，路径前后必须保留斜杠：

• .env.production（生产环境）

# vue-cli版本
VUE_APP_DEPLOY_PATH = /app1/
# Vite版本替换为 VITE_DEPLOY_PATH = /app1/

• .env.staging（预发环境）

# vue-cli版本
VUE_APP_DEPLOY_PATH = /staging/app1/
# Vite版本替换为 VITE_DEPLOY_PATH = /staging/app1/

• .env.dev（开发部署环境）

# vue-cli版本
VUE_APP_DEPLOY_PATH = /dev/app1/
# Vite版本替换为 VITE_DEPLOY_PATH = /dev/app1/

在package.json中新增对应环境的打包命令：

{
  "scripts": {
    "build:prod": "vue-cli-service build --mode production",
    "build:staging": "vue-cli-service build --mode staging",
    "build:dev": "vue-cli-service build --mode dev"
    // Vite构建将vue-cli-service替换为vite build即可
  }
}

所有应用重复上述配置，仅需把app1替换为对应应用的标识即可。 #

2. 服务器部署目录结构配置 #

在NGINX站点根目录（默认路径为/usr/share/nginx/html，可自定义）下建立如下层级目录：

html/
├── app1/          # 生产环境app1打包后dist内的所有文件直接存入该目录
├── app2/          # 生产环境app2打包后dist内的所有文件直接存入该目录
├── app3/          # 生产环境app3打包后dist内的所有文件直接存入该目录
├── staging/
│   ├── app1/      # 预发环境app1打包后dist内的所有文件直接存入该目录
│   ├── app2/      # 预发环境app2打包后dist内的所有文件直接存入该目录
│   └── app3/      # 预发环境app3打包后dist内的所有文件直接存入该目录
└── dev/
    ├── app1/      # 开发环境app1打包后dist内的所有文件直接存入该目录
    ├── app2/      # 开发环境app2打包后dist内的所有文件直接存入该目录
    └── app3/      # 开发环境app3打包后dist内的所有文件直接存入该目录

注意：不要在对应子目录下套多余的dist文件夹，确保index.html直接在对应子路径根目录下 #

3. NGINX 配置 #

修改NGINX站点配置文件（默认路径为/etc/nginx/conf.d/default.conf，可自定义）：

server {
    listen 80;
    server_name mydomain.com; # 替换为实际使用的域名
    root /usr/share/nginx/html; # 替换为实际的NGINX站点根目录路径
    index index.html index.htm;

    # 生产环境应用规则
    location ^~ /app1 {
        try_files $uri $uri/ /app1/index.html;
    }
    location ^~ /app2 {
        try_files $uri $uri/ /app2/index.html;
    }
    location ^~ /app3 {
        try_files $uri $uri/ /app3/index.html;
    }

    # 预发环境应用规则
    location ^~ /staging/app1 {
        try_files $uri $uri/ /staging/app1/index.html;
    }
    location ^~ /staging/app2 {
        try_files $uri $uri/ /staging/app2/index.html;
    }
    location ^~ /staging/app3 {
        try_files $uri $uri/ /staging/app3/index.html;
    }

    # 开发环境应用规则
    location ^~ /dev/app1 {
        try_files $uri $uri/ /dev/app1/index.html;
    }
    location ^~ /dev/app2 {
        try_files $uri $uri/ /dev/app2/index.html;
    }
    location ^~ /dev/app3 {
        try_files $uri $uri/ /dev/app3/index.html;
    }

    # 其余原有配置（日志、gzip、跨域等）保持不变
}

配置完成后执行命令生效：

• 验证配置合法性：nginx -t
• 重载NGINX服务：nginx -s reload

4. 常见问题排查 #

• 静态资源404：优先检查publicPath/base参数是否与部署子路径完全一致，路径前后必须带斜杠
• 路由跳转后刷新404：检查NGINX配置中对应路径的try_files规则是否正确指向该应用的index.html
• 环境路径不匹配：确认打包时使用了对应环境的打包命令，加载了正确的环境变量

内容的提问来源于stack exchange，提问作者Malay Thakershi