在前端开发中，我们常遇到需要将多个Vue项目部署在同一域名下的情况，比如
https://yourdomain.com/app1/和
https://yourdomain.com/app2/。这时子文件夹部署就成了必备技能。今天就带大家从零开始，手把手教你搞定Vue项目的子文件夹部署，涵盖Vue CLI、Vite两种构建工具，Nginx、Apache两种服务器配置，以及90%的人都会踩的坑和解决方案！

一、为什么需要子文件夹部署？

想象一下，公司官网、管理后台、活动页面都用Vue开发，如果每个项目都占一个域名，不仅成本高，服务器资源也浪费。通过子文件夹部署，我们可以把多个项目放在同一域名下，比如：

• 官网：https://yourdomain.com/
• 管理后台：https://yourdomain.com/admin/
• 活动页面：https://yourdomain.com/campaign/

这样既节省资源，又方便用户记忆。但Vue项目默认是根目录部署，直接放子文件夹会出现404错误、静态资源加载失败等问题。别慌，跟着下面步骤操作，轻松解决！

二、核心配置：3步搞定项目打包

1. 设置资源基础路径（关键！）

Vue CLI项目（Vue 2常用）：
在项目根目录的vue.config.js中添加publicPath，值为你的子文件夹路径（必须以/开头和结尾）：

// vue.config.js
module.exports = {
  publicPath: '/admin/', // 子文件夹路径，比如/admin/
  outputDir: 'dist', // 打包输出目录，默认dist
  assetsDir: 'static' // 静态资源目录，默认static
}

Vite项目（Vue 3常用）：
在vite.config.js中设置base，和Vue CLI的publicPath作用相同：

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

export default defineConfig({
  base: '/admin/', // 子文件夹路径，和Vue CLI的publicPath一致
  plugins: [vue()]
})

为什么要设置这个？
打包时，HTML里引用的JS/CSS路径会自动加上/admin/前缀，比如<script src="/admin/static/js/app.js">，确保资源能正确加载。

2. 配置路由（避免刷新404）

如果用Vue Router的history模式（URL无#），必须设置base属性，值和上面的publicPath一致：

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory('/admin/'), // 必须和publicPath/base一致！
  routes: [
    { path: '/', component: Home },
    { path: '/about', component: About }
  ]
})

export default router

注意：如果用hash模式（URL带#），虽然不用服务器配置，但URL不美观，建议优先用history模式。

3. 本地预览（提前踩坑）

打包前先用npm run preview本地预览，确保没问题再部署：

# Vue CLI
npm run build
npm run preview -- --port 8080 # 访问 http://localhost:8080/admin/ 测试

# Vite
npm run build
vite preview --port 8080 # 同样访问子路径测试

如果本地预览出现白屏，先检查控制台报错：

• 404：资源路径不对，检查publicPath是否正确
• 路由跳转失败：检查router.base是否和publicPath一致

三、服务器配置：Nginx/Apache任选

1. Nginx配置（推荐）

Nginx性能好、配置简单，是生产环境首选。打开Nginx配置文件（通常在/etc/nginx/nginx.conf或
/etc/nginx/conf.d/yourdomain.conf），添加子文件夹配置：

server {
  listen 80;
  server_name yourdomain.com;

  # 主项目（根目录部署）
  location / {
    root /var/www/main;
    try_files $uri $uri/ /index.html;
  }

  # 子项目admin（子文件夹部署）
  location /admin {
    alias /var/www/admin/dist; # 指向打包后的dist目录
    try_files $uri $uri/ /admin/index.html; # 关键！解决刷新404
    index index.html;
  }
}

配置说明：

• alias：指定子项目的文件路径（区别于root，不会拼接location路径）
• try_files：当请求的文件/目录不存在时，回退到/admin/index.html，让Vue Router处理路由

配置完重启Nginx：

sudo nginx -t # 检查配置是否有误
sudo nginx -s reload # 重启生效

2. Apache配置（备选）

如果服务器用Apache，需要两步：

第一步：修改Apache配置文件（httpd.conf）

开启mod_rewrite模块（去掉#）：

LoadModule rewrite_module modules/mod_rewrite.so

设置AllowOverride All（允许.htaccess文件生效）：

<Directory "/var/www/html">
  AllowOverride All
</Directory>

第二步：在子项目目录添加.htaccess文件

在/var/www/admin/dist目录下新建.htaccess，写入：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /admin/ # 和publicPath一致
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /admin/index.html [L] # 路由回退到index.html
</IfModule>

重启Apache生效：

sudo systemctl restart httpd # CentOS
# 或
sudo service apache2 restart # Ubuntu

四、90%的人会踩的3个坑及解决方案

1. 静态资源加载404（最常见！）

症状：页面空白，控制台提示Failed to load resource: 404
原因：publicPath配置错误，或路由base和publicPath不一致
解决：

• 确保publicPath/base以/开头和结尾（如/admin/，不是admin或/admin）
• 路由createWebHistory('/admin/')中的路径必须和publicPath完全一致

2. 刷新页面404（history模式必现）

症状：直接访问
https://yourdomain.com/admin/about正常，刷新后404
原因：服务器未配置路由回退，把前端路由当成静态文件请求
解决：

• Nginx：配置try_files $uri $uri/ /admin/index.html;
• Apache：通过.htaccess文件设置RewriteRule

3. 多项目冲突（同一服务器部署多个Vue项目）

症状：/admin/和/campaign/两个项目，访问其中一个会跳转到另一个
原因：Nginx的location匹配规则错误，或alias/root混用
解决：

• 用location ^~ /admin（^~表示优先匹配）
• 子项目用alias，根项目用root，避免路径拼接错误：# 正确示例 location ^~ /admin { alias /var/www/admin/dist; # 子项目用alias try_files $uri $uri/ /admin/index.html; }

location / { root /var/www/main; # 根项目用root try_files $uri $uri/ /index.html; }

五、企业级实战案例：某电商后台部署

某电商平台需要将管理后台部署在`https://shop.com/admin/`，步骤如下：

1. **项目配置**（Vue CLI）：
```javascript
// vue.config.js
module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/admin/' : '/', // 区分环境
  outputDir: 'dist/admin' // 打包到dist/admin，方便上传
}

// router/index.js
const router = createRouter({
  history: createWebHistory('/admin/'),
  routes: [...]
})

1. Nginx配置：
2. server { listen 443 ssl; server_name shop.com; # SSL配置省略... location ^~ /admin { alias /var/www/shop/admin; # 指向服务器上的dist/admin目录 try_files $uri $uri/ /admin/index.html; expires 1d; # 静态资源缓存1天 } }
3. 部署效果： 访问https://shop.com/admin正常加载，刷新、路由跳转无压力，静态资源CDN加速后首次加载速度提升60%。

六、部署前检查清单（必看！）

为避免上线后踩坑，部署前务必检查以下几点：

• publicPath/base是否为/子文件夹/格式
• 路由base是否和publicPath一致
• 服务器try_files/.htaccess配置是否添加
• 本地npm run preview测试子路径访问正常
• 静态资源（图片、字体）路径是否用相对路径（如@/assets/logo.png）

总结

子文件夹部署看似复杂，实则掌握核心配置（publicPath、路由base、服务器回退）就能轻松搞定。无论是个人项目还是企业级应用，这一技能都能帮你节省服务器成本、优化资源管理。

如果觉得本文有用，欢迎点赞收藏！部署中遇到问题，评论区留言，我会一一解答～

参考资料：

Vue官方文档 - 生产环境部署Vue Router - History模式Nginx配置指南

（注：文中图片来源网络，侵删）