Vue 項目多級路徑部署終極指南：基于環境變量的統一配置方案
作者：天藍色的魚
本文將提供一個完整的解決方案，從環境變量配置到Nginx部署，確保你的Vue項目可以靈活部署在任何路徑下。
本文將提供一個完整的解決方案，從環境變量配置到Nginx部署，確保你的Vue項目可以靈活部署在任何路徑下。
一、環境變量統一配置
1. 環境變量配置文件
我們首先在項目根目錄創建以下環境文件：
# .env.development
VUE_APP_BASE_URL=/
VUE_APP_PUBLIC_PATH=/
VUE_APP_API_BASE_URL=/api/# .env.production
VUE_APP_BASE_URL=/department/project/
VUE_APP_PUBLIC_PATH=/department/project/
VUE_APP_API_BASE_URL=/department/project/api/關鍵點說明：
- VUE_APP_BASE_URL: 路由基礎路徑
- VUE_APP_PUBLIC_PATH: 靜態資源基礎路徑
- VUE_APP_API_BASE_URL: API請求基礎路徑
二、Vue項目核心配置
1. vue.config.js 完整配置
const path = require('path')
module.exports = {
// 靜態資源路徑
publicPath: process.env.VUE_APP_PUBLIC_PATH || '/',
// 輸出目錄
outputDir: 'dist',
// 靜態資源目錄
assetsDir: 'static',
// 文件名哈希
filenameHashing: true,
// webpack配置
chainWebpack: config => {
// 設置publicPath
config.output
.publicPath(process.env.VUE_APP_PUBLIC_PATH || '/')
// 圖片處理
config.module
.rule('images')
.use('url-loader')
.loader('url-loader')
.tap(options => {
options.limit = 8192
options.fallback = {
loader: 'file-loader',
options: {
name: 'static/img/[name].[hash:8].[ext]',
publicPath: process.env.VUE_APP_PUBLIC_PATH || '/'
}
}
return options
})
},
// 開發服務器配置
devServer: {
// 支持history模式
historyApiFallback: {
disableDotRule: true,
rewrites: [
{
from: newRegExp('^.*'),
to: path.posix.join(process.env.VUE_APP_PUBLIC_PATH || '/', 'index.html')
}
]
},
// 代理配置
proxy: {
[process.env.VUE_APP_API_BASE_URL]: {
target: 'http://your-api-server.com',
changeOrigin: true,
pathRewrite: {
[`^${process.env.VUE_APP_API_BASE_URL}`]: ''
}
}
}
},
// 生產環境關閉sourcemap
productionSourceMap: false
}三、路由配置優秀實踐
1. 路由配置文件 (src/router/index.js)
import Vue from'vue'
import VueRouter from'vue-router'
Vue.use(VueRouter)
// 獲取基礎路徑，確保不以斜杠結尾
const BASE_PATH = (process.env.VUE_APP_BASE_URL || '/').replace(/\/$/, '')
const routes = [
{
// 根路徑重定向
path: '',
redirect: 'home'
},
{
// 注意：不要以斜杠開頭
path: 'home',
component: () =>import('@/views/Home.vue'),
name: 'home',
meta: { title: '首頁' }
},
{
path: 'about',
component: () =>import('@/views/About.vue'),
name: 'about',
meta: { title: '關于我們' }
},
{
path: '*',
component: () =>import('@/views/NotFound.vue'),
name: 'not-found',
meta: { title: '頁面不存在' }
}
]
const router = new VueRouter({
mode: 'history',
base: BASE_PATH,
routes,
// 滾動行為
scrollBehavior(to, from, savedPosition) {
if (savedPosition) {
return savedPosition
} else {
return { x: 0, y: 0 }
}
}
})
router.beforeEach((to, from, next) => {
document.title = to.meta.title || '默認標題'
next()
})
exportdefault router四、資源加載與API請求規范
1. 資源加載工具類 (src/utils/resource.js)
/**
* 獲取靜態資源完整URL
* @param {string} relativePath 相對路徑
* @returns {string} 完整URL
*/
exportconst getAssetUrl = (relativePath) => {
const baseUrl = process.env.VUE_APP_PUBLIC_PATH || '/'
return`${baseUrl.replace(/\/$/, '')}/${relativePath.replace(/^\//, '')}`
}
/**
* 獲取API完整URL
* @param {string} endpoint API端點
* @returns {string} 完整API URL
*/
exportconst getApiUrl = (endpoint) => {
const baseUrl = process.env.VUE_APP_API_BASE_URL || '/api/'
return`${baseUrl.replace(/\/$/, '')}/${endpoint.replace(/^\//, '')}`
}2. Axios實例配置 (src/utils/request.js)
import axios from'axios'
import { getApiUrl } from'./resource'
// 創建axios實例
const service = axios.create({
baseURL: process.env.VUE_APP_API_BASE_URL,
timeout: 10000
})
// 請求攔截器
service.interceptors.request.use(
config => {
// 可以在這里添加token等
// config.headers['Authorization'] = getToken()
return config
},
error => {
returnPromise.reject(error)
}
)
// 響應攔截器
service.interceptors.response.use(
response => {
return response.data
},
error => {
returnPromise.reject(error)
}
)
exportdefault service五、Nginx服務器配置
1. 基礎Nginx配置
server {
listen 80;
server_name example.com;
# 靜態資源緩存設置
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, no-transform";
}
# 項目部署路徑 - 使用環境變量中的路徑
location /department/project/ {
alias /var/www/html/department/project/dist/;
try_files $uri $uri/ /department/project/index.html;
# 開啟gzip壓縮
gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml;
# 安全頭設置
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header X-XSS-Protection "1; mode=block";
}
# API代理
location /department/project/api/ {
proxy_pass http://api-server/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}2. HTTPS增強配置
server {
listen 443 ssl http2;
server_name example.com;
ssl_certificate /etc/ssl/certs/example.com.crt;
ssl_certificate_key /etc/ssl/private/example.com.key;
# SSL優化配置
ssl_session_timeout 1d;
ssl_session_cache shared:MozSSL:10m;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
location /department/project/ {
alias /var/www/html/department/project/dist/;
try_files $uri $uri/ /department/project/index.html;
# 安全頭
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header Content-Security-Policy "default-src 'self'";
}
}六、完整部署流程
1. 構建與部署腳本
#!/bin/bash
# 設置環境
ENV="production"
DEPLOY_PATH="/var/www/html/department/project"
# 安裝依賴
npm install
# 構建項目
npm run build:${ENV}
# 同步文件到服務器
rsync -avz --delete dist/ user@server:${DEPLOY_PATH}/dist/
# 重啟Nginx
ssh user@server "sudo systemctl restart nginx"
echo"Deployment completed!"2. 多環境構建腳本 (package.json)
{
"scripts": {
"serve": "vue-cli-service serve",
"build": "vue-cli-service build",
"build:dev": "vue-cli-service build --mode development",
"build:test": "vue-cli-service build --mode test",
"build:production": "vue-cli-service build --mode production",
"lint": "vue-cli-service lint"
}
}七、常見問題解決方案
1. 頁面刷新404問題
解決方案：
- 確保Nginx配置中包含正確的try_files指令
- 檢查Vue路由的base配置是否與環境變量一致
- 驗證publicPath配置是否正確
2. 靜態資源加載失敗
排查步驟：
- 檢查瀏覽器開發者工具中的網絡請求
- 確認請求路徑是否包含正確的基礎路徑
- 驗證Nginx的alias路徑是否正確
- 檢查文件權限：chmod -R 755 /var/www/html
3. API請求路徑錯誤
最佳實踐：
- 使用axios實例配置baseURL
- 確保API路徑與VUE_APP_API_BASE_URL一致
- 開發環境使用代理，生產環境使用絕對路徑
八、性能優化建議
資源壓縮：
- 開啟Nginx gzip壓縮
- 使用Brotli壓縮（需要Nginx支持）
- 壓縮圖片資源
緩存策略：
location ~* \.(js|css)$ {
expires 365d;
add_header Cache-Control "public";
}
location ~* \.(jpg|jpeg|png|gif|ico)$ {
expires 30d;
add_header Cache-Control "public";
}代碼分割：
// 使用動態導入實現路由懶加載
component: () => import('@/views/Home.vue')九、總結
這種方案在多個大型項目中得到驗證，能夠滿足企業級應用的部署需求。希望本指南能幫助你解決Vue項目在多級路徑下的部署問題！
責任編輯：趙寧寧
來源：
大前端歷險記
