JPwise-docs

Appearance

JPwise-Web 部署构建文档 - Claude Code ​

🔧 环境配置 ​

开发环境配置 ​

文件位置：src/utils/define.js

javascript
export const APIUrl = "http://localhost:30000";  // 后端 API 地址
export const baseURL = APIUrl + basePath;        // 完整 API 地址

生产环境配置 ​

文件位置：public/config.js

javascript
window.SITE_CONFIG = {
  APIUrl: 'https://your-domain.com/api',  // 生产 API 地址
  version: '3.4.2',
  title: 'JPwise智能平台'
};

🚀 核心构建命令 ​

日常开发 ​

bash
npm install              # 安装依赖
npm run dev             # 启动开发服务器（自动打开浏览器）
npm run lint -- --fix   # 代码格式修复
npm run build           # 生产构建

清理和修复 ​

bash
# 清理缓存重新安装
npm cache clean --force && npm install

# 检查特定文件
npm run lint src/views/specific-file.vue

测试和分析 ​

bash
npm run test:unit       # 单元测试
npm run test:ci         # CI测试（lint + 单元测试）
npm run build -- --report  # 构建并分析包大小

📦 部署流程 ​

本地构建部署 ​

bash
# 标准构建流程
git pull origin master     # 拉取最新代码
npm install                # 安装依赖  
npm run lint               # 代码检查
npm run test:unit          # 运行测试
npm run build              # 生产构建
# 将 dist 目录部署到服务器

Docker 部署 ​

Dockerfile ​

dockerfile
# 构建阶段
FROM node:16-alpine as build-stage
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 生产阶段  
FROM nginx:stable-alpine as production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

构建和启动 ​

bash
# 构建 Docker 镜像
docker build -t jpwise-web:latest .

# 启动容器
docker run -d -p 80:80 jpwise-web:latest

Nginx 配置 ​

nginx
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/jpwise-web/dist;
    index index.html;

    # 前端路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://backend-server:30000/api/;
        proxy_set_header Host $host;
    }

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

⚡ 构建优化 ​

webpack 优化配置 ​

文件位置：vue.config.js

javascript
module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
  outputDir: 'dist',
  
  // 开发服务器
  devServer: {
    port: 3000,
    open: true,
    proxy: {
      '/api': {
        target: 'http://localhost:30000',
        changeOrigin: true
      }
    }
  },
  
  // 构建优化
  configureWebpack: {
    optimization: {
      splitChunks: {
        chunks: 'all',
        cacheGroups: {
          vendor: {
            test: /[\\/]node_modules[\\/]/,
            name: 'vendors',
            chunks: 'all'
          }
        }
      }
    }
  }
};

资源压缩 ​

javascript
// 生产环境 Gzip 压缩
const CompressionPlugin = require('compression-webpack-plugin');

configureWebpack: {
  plugins: process.env.NODE_ENV === 'production' ? [
    new CompressionPlugin({
      test: /\.(js|css|html|svg)$/,
      threshold: 8192
    })
  ] : []
}

🌍 环境变量管理 ​

环境文件 ​

bash
# .env.development
NODE_ENV=development
VUE_APP_API_URL=http://localhost:30000

# .env.production  
NODE_ENV=production
VUE_APP_API_URL=https://api.your-domain.com

代码中使用 ​

javascript
const apiUrl = process.env.VUE_APP_API_URL;

if (process.env.NODE_ENV === 'development') {
  console.log('开发环境');
}

🔍 CI/CD 自动化 ​

GitHub Actions 示例 ​

yaml
name: Deploy to Production

on:
  push:
    branches: [ master ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
        cache: 'npm'
    
    - name: Install and Test
      run: |
        npm ci
        npm run test:ci
    
    - name: Build
      run: npm run build
    
    - name: Deploy
      run: rsync -avz --delete dist/ user@server:/var/www/jpwise-web/

📊 监控和调试 ​

构建分析 ​

bash
# 包大小分析
npm run build -- --report
npx webpack-bundle-analyzer dist/static/js/*.js

运行时监控 ​

javascript
// 错误监控
window.addEventListener('error', (event) => {
  console.error('Runtime Error:', event.error);
});

// 性能监控
window.addEventListener('load', () => {
  const perfData = performance.getEntriesByType('navigation')[0];
  console.log('页面加载时间:', perfData.loadEventEnd - perfData.fetchStart);
});

🆘 故障处理 ​

构建失败 ​

bash
# 清理重建
rm -rf node_modules dist
npm cache clean --force
npm install
npm run build

常见问题 ​

  • 静态资源 404：检查 publicPath 配置
  • API 连接失败：验证 nginx 代理配置
  • 路由 404：确认 nginx 前端路由配置

快速回滚 ​

bash
# 停止服务
systemctl stop nginx

# 恢复备份
mv /var/www/jpwise-web /var/www/jpwise-web-failed  
mv /var/www/jpwise-web-backup /var/www/jpwise-web

# 重启服务
systemctl start nginx

✅ 部署检查清单 ​

部署前 ​

  • [ ] 代码已合并到主分支
  • [ ] 通过 npm run test:ci
  • [ ] 环境配置已确认
  • [ ] API 接口连接正常

部署后 ​

  • [ ] 页面正常加载
  • [ ] 控制台无错误
  • [ ] 核心功能测试通过
  • [ ] 移动端适配正常

部署构建要点：环境配置 + 构建命令 + 部署流程 + 故障处理