all-project/docs/部署文档/web前端生产环境部署指南.md

Web前端生产环境部署指南

📋 部署概述

本指南说明如何将Web前端工程部署到生产环境，后端API地址为：http://47.121.125.41:8080/

🔧 已完成配置

1. 生产环境API配置修改

已将生产环境配置文件 web/.env.production 中的API地址修改为：

# 原配置
VITE_APP_BASE_API = '/prod-api'

# 新配置 
VITE_APP_BASE_API = 'http://47.121.125.41:8080'

2. 配置文件备份

原始配置文件已备份为：web/.env.production.backup

🚀 部署步骤

步骤1：安装依赖并构建

# 进入web工程目录
cd web

# 安装依赖（如果还没有安装）
npm install

# 构建生产环境版本
npm run build:prod

构建脚本将 Node 堆上限设为 6144MB。4096MB 会在 transform 阶段被活对象占满（约 4091MB，GC 几乎无法回收）并报 JavaScript heap out of memory。本机物理内存为 8GB，因此不用 8192MB。同时限制 Rollup 并行读文件数，避免打包时把文件一次性读进内存。Element Plus 与 animate.css 改为普通 CSS 引入，不再经由 Sass 编译。构建已关闭控制台 gzip 体积统计，且小于 10KB 的分包不再预生成 .gz（较大的 js/css 仍会生成，供 nginx gzip_static 使用）。Element Plus 样式全量引入，打包时不再按组件重复引入样式。

步骤2：验证构建产物

# 构建完成后，检查dist目录
ls -la dist/

# 应该包含以下文件/目录：
# - index.html (主页面)
# - assets/ (静态资源：CSS、JS、图片等)
# - favicon.ico (网站图标)

步骤3：部署到Web服务器

选项A：直接上传静态文件（推荐）

1. 将 dist/ 目录下的所有文件上传到Web服务器的根目录
2. 确保Web服务器支持HTML5 History模式（SPA路由）

选项B：使用Docker部署

# Dockerfile示例
FROM nginx:alpine

# 复制构建产物到nginx目录
COPY dist/ /usr/share/nginx/html/

# 复制nginx配置（可选）
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

步骤4：Web服务器配置

Nginx配置示例

如果使用Nginx作为Web服务器，需要配置支持Vue Router的History模式：

server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    # 支持Vue Router History模式
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存配置
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Gzip压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

Apache配置示例

如果使用Apache，需要在网站根目录创建 .htaccess 文件：

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
</IfModule>

🔍 部署验证

1. 功能验证

部署完成后，访问网站进行以下验证：

# 访问主页
curl -I http://your-domain.com

# 检查API请求是否正常
# 在浏览器开发者工具中查看网络请求
# 确认API请求指向：http://47.121.125.41:8080

2. 关键检查点

• 页面正常加载
• 登录功能正常
• API请求指向正确的后端地址
• 路由跳转正常（刷新页面不出现404）
• 静态资源加载正常
• 浏览器控制台无错误

🌐 CORS配置注意事项

由于前端直接访问后端API，需要确保后端服务器配置了正确的CORS策略：

后端CORS配置检查

确保后端 application.yml 中包含以下配置：

# CORS配置
cors:
  # 允许的域名，部署后需要添加前端域名
  allowed-origins:
    - http://localhost
    - http://localhost:80
    - http://your-frontend-domain.com  # 添加你的前端域名
  allowed-methods: GET,POST,PUT,DELETE,OPTIONS
  allowed-headers: "*"
  allow-credentials: true

🔒 安全配置建议

1. HTTPS配置

生产环境建议使用HTTPS：

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    
    # 其他配置...
}

# HTTP重定向到HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

2. 安全头配置

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

🔄 替代部署方案：Nginx代理方式

如果不想修改前端配置，可以保持原始配置 VITE_APP_BASE_API = '/prod-api'，通过Nginx代理：

1. 恢复原始配置

# 恢复原始配置（如果需要）
cp web/.env.production.backup web/.env.production

# 重新构建
cd web && npm run build:prod

2. Nginx代理配置

server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    # 前端静态文件
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API代理到后端服务器
    location /prod-api/ {
        proxy_pass http://47.121.125.41:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # CORS处理
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,clientid';
        
        if ($request_method = 'OPTIONS') {
            return 204;
        }
    }
}

📊 性能优化建议

1. 构建优化

# 使用生产环境构建（已启用压缩）
npm run build:prod

# 检查构建产物大小
du -sh dist/

2. CDN配置

对于静态资源，建议使用CDN加速：

# 静态资源使用CDN
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    
    # 如果有CDN，可以设置重定向
    # return 301 https://cdn.your-domain.com$request_uri;
}

🚨 故障排查

常见问题及解决方案

1. 页面刷新出现404

   • 检查Web服务器是否配置了SPA路由支持
   • 确认 try_files 配置正确

2. API请求失败

   • 检查后端服务是否正常运行
   • 验证CORS配置
   • 检查防火墙和安全组设置

3. 静态资源加载失败

   • 检查文件路径和权限
   • 验证Web服务器配置

4. 登录功能异常

   • 检查加密配置是否与后端一致
   • 验证客户端ID配置

📝 部署检查清单

• 环境配置文件已正确修改
• 项目构建成功
• 静态文件已上传到Web服务器
• Web服务器配置正确
• 后端API地址可访问
• CORS配置正确
• 所有功能测试通过
• 性能测试通过
• 安全配置完成

🔄 部署脚本示例

#!/bin/bash
# deploy.sh - 自动化部署脚本

echo "开始部署Web前端..."

# 1. 构建项目
cd web
echo "正在安装依赖..."
npm install

echo "正在构建生产版本..."
npm run build:prod

# 2. 备份现有部署
if [ -d "/var/www/html.backup" ]; then
    rm -rf /var/www/html.backup
fi
cp -r /var/www/html /var/www/html.backup

# 3. 部署新版本
echo "正在部署新版本..."
rm -rf /var/www/html/*
cp -r dist/* /var/www/html/

# 4. 重启Web服务器
echo "正在重启Web服务器..."
sudo systemctl reload nginx

echo "部署完成！"
echo "请访问: http://your-domain.com"

---

部署完成后，前端应用将通过配置的域名访问，所有API请求将直接指向 http://47.121.125.41:8080/