Dream-MachineProcurementList/DEPLOYMENT.md

部署指南

本文档详细说明如何在不同环境中部署 Dream-Machine 采购清单管理系统。

🚀 快速部署

使用 Makefile（推荐）

# 完整部署检查流程
make pre-deploy

# 或分步执行
make clean-install  # 清理并安装依赖
make lint          # 代码质量检查
make build         # 构建生产版本
make preview       # 本地预览测试

🏗 开发环境设置

系统要求

• 操作系统: Windows 10+, macOS 10.15+, Ubuntu 18.04+
• Node.js: v18.0.0 或更高版本
• 内存: 最少 4GB RAM
• 存储: 至少 1GB 可用空间

开发环境启动

1. 克隆项目

   git clone <repository-url>
   cd dream-machine-purchase-list
   

2. 环境检查

   make info  # 查看系统信息
   

3. 启动开发服务器

   make dev   # 自动安装依赖并启动
   

4. 访问应用

   • 开发服务器: http://localhost:5173
   • 网络访问: http://[你的IP]:5173

开发环境配置

Vite 配置

// vite.config.ts 关键配置
export default defineConfig({
  server: {
    port: 5173,        // 开发服务器端口
    host: true,        // 允许外部访问
    open: true,        // 自动打开浏览器
    hmr: {
      port: 5173       // 热重载端口
    }
  }
})

环境变量

# .env.local (可选)
VITE_APP_TITLE="Dream-Machine 采购清单"
VITE_APP_VERSION="1.0.0"

🏭 生产环境部署

构建优化

1. 生产构建

   make build
   

2. 构建文件分析

   make size-check  # 检查文件大小
   

3. 生产预览

   make preview     # 本地预览生产版本
   

静态托管部署

Netlify 部署

1. 构建设置

   # netlify.toml
   [build]
     publish = "dist"
     command = "npm run build"
   
   [build.environment]
     NODE_VERSION = "18"
   
   [[redirects]]
     from = "/*"
     to = "/index.html"
     status = 200
   

2. 部署步骤

   # 本地构建
   make build
   
   # 上传 dist 目录到 Netlify
   

Vercel 部署

1. 配置文件

   {
     "buildCommand": "npm run build",
     "outputDirectory": "dist",
     "framework": "vite"
   }
   

2. 自动部署

   • 连接 GitHub 仓库
   • 自动检测 Vite 项目
   • 推送代码自动部署

GitHub Pages 部署

1. 配置 vite.config.ts

   export default defineConfig({
     base: '/your-repo-name/',
     build: {
       outDir: 'dist'
     }
   })
   

2. GitHub Actions 配置

   # .github/workflows/deploy.yml
   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [ main ]
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - uses: actions/setup-node@v3
           with:
             node-version: '18'
         - run: npm ci
         - run: npm run build
         - uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist
   

服务器部署

Nginx 配置

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/dream-machine/dist;
    index index.html;

    # 单页应用路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets/ {
        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;
}

Docker 部署

1. Dockerfile

   # 多阶段构建
   FROM node:18-alpine as builder
   
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   
   COPY . .
   RUN npm run build
   
   # 生产镜像
   FROM nginx:alpine
   COPY --from=builder /app/dist /usr/share/nginx/html
   COPY nginx.conf /etc/nginx/nginx.conf
   
   EXPOSE 80
   CMD ["nginx", "-g", "daemon off;"]
   

2. 构建和运行

   # 构建镜像
   docker build -t dream-machine-app .
   
   # 运行容器
   docker run -p 80:80 dream-machine-app
   

🔧 性能优化

构建优化

1. Bundle 分析

   # 安装分析工具
   npm install --save-dev rollup-plugin-visualizer
   
   # 生成分析报告
   npm run build
   

2. 代码分割

   // 路由级别代码分割
   const HomePage = lazy(() => import('@/pages/HomePage'))
   const NotFoundPage = lazy(() => import('@/pages/NotFoundPage'))
   

3. 资源优化

   // vite.config.ts
   export default defineConfig({
     build: {
       rollupOptions: {
         output: {
           manualChunks: {
             vendor: ['react', 'react-dom'],
             ui: ['@radix-ui/react-dialog', '@radix-ui/react-select']
           }
         }
       }
     }
   })
   

运行时优化

1. 图片优化

   • 使用 WebP 格式
   • 启用懒加载
   • 设置合适的尺寸

2. 缓存策略

   // Service Worker 缓存
   const CACHE_NAME = 'dream-machine-v1'
   const urlsToCache = [
     '/',
     '/static/css/main.css',
     '/static/js/main.js'
   ]
   

📊 监控和维护

错误监控

1. 错误边界

   class ErrorBoundary extends Component {
     componentDidCatch(error, errorInfo) {
       console.error('Error caught:', error, errorInfo)
     }
   }
   

2. 性能监控

   // 性能指标收集
   import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals'
   
   getCLS(console.log)
   getFID(console.log)
   getFCP(console.log)
   getLCP(console.log)
   getTTFB(console.log)
   

健康检查

# 部署后检查清单
make test-flow    # 完整测试流程

# 手动检查项目
- [ ] 页面正常加载
- [ ] 数据导入导出功能正常
- [ ] 响应式设计正常
- [ ] 打印功能正常
- [ ] 数据持久化正常

🔒 安全考虑

内容安全策略

<meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' 'unsafe-inline'; 
               style-src 'self' 'unsafe-inline';
               img-src 'self' data: https:;">

HTTPS 配置

server {
    listen 443 ssl http2;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    
    # 安全头
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
}

🚨 故障排除

常见问题

1. 构建失败

   make clean-install  # 清理重装
   make lint          # 检查代码
   

2. 内存不足

   # 增加 Node.js 内存限制
   export NODE_OPTIONS="--max-old-space-size=4096"
   npm run build
   

3. 端口冲突

   # 检查端口占用
   lsof -i :5173
   
   # 杀死进程
   kill -9 <PID>
   

调试工具

# 构建详细日志
npm run build -- --debug

# 网络请求调试
npm run dev -- --host 0.0.0.0 --debug

# 内存使用分析
node --inspect npm run build

---

需要帮助？查看 README.md 或创建 Issue。