Qwerty Learner 的部署与运行

2026-02-04 04:44:02作者：裘旻烁

🎯 项目概述

Qwerty Learner 是一款专为键盘工作者设计的单词记忆与英语肌肉记忆锻炼软件。该项目结合了 React、TypeScript、Vite 和 Tauri 技术栈，提供 Web 应用和桌面应用两种部署方式。

通过本文，您将掌握：

✅ 本地开发环境搭建与运行
✅ Docker 容器化部署方案
✅ Tauri 桌面应用构建方法
✅ 生产环境部署最佳实践
✅ 常见问题排查与解决方案

📋 环境要求

在开始部署前，请确保您的系统满足以下要求：

组件	最低版本	推荐版本	说明
Node.js	16.x	18.x+	JavaScript 运行时环境
npm/yarn	6.x	8.x+	包管理工具
Git	2.x	2.30.x+	版本控制系统
Rust (可选)	1.60+	1.70+	Tauri 桌面应用构建

🚀 快速开始

1. 克隆项目仓库

git clone https://gitcode.com/RealKai42/qwerty-learner.git
cd qwerty-learner

2. 安装依赖

# 使用 yarn（推荐）
yarn install

# 或使用 npm
npm install

3. 启动开发服务器

# 开发模式
yarn dev

# 或
npm run dev

项目将在 http://localhost:5173 启动，支持热重载功能。

🐳 Docker 部署

单容器部署

项目提供了完整的 Docker 支持，使用以下命令快速部署：

# 构建镜像
docker build -t qwerty-learner .

# 运行容器
docker run -p 8990:5173 qwerty-learner

Docker Compose 部署

使用 docker-compose 进行更便捷的容器管理：

version: '3'

services:
  qwertylearner:
    build: .
    ports:
      - '8990:5173'
    restart: unless-stopped

启动命令：

docker-compose up -d

🖥️ Tauri 桌面应用

环境准备

构建桌面应用需要安装 Rust 环境：

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装 Tauri CLI
cargo install tauri-cli

# 或使用 npm
npm install -g @tauri-apps/cli

构建桌面应用

# 进入 Tauri 目录
cd src-tauri

# 构建应用
cargo tauri build

# 或使用 npm 脚本
npm run tauri build

构建完成后，可在 src-tauri/target/release 目录找到可执行文件。

🏗️ 生产环境部署

Vite 构建配置

项目使用 Vite 进行构建优化：

// vite.config.ts 关键配置
export default defineConfig({
  build: {
    minify: true,          // 代码压缩
    outDir: 'build',       // 输出目录
    sourcemap: false,      // 生产环境关闭 sourcemap
  },
  esbuild: {
    drop: ['console', 'debugger'], // 移除调试代码
  }
})

构建生产版本

# 构建生产版本
yarn build

# 输出目录：./build/

Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    
    root /path/to/qwerty-learner/build;
    index index.html;
    
    # 处理 SPA 路由
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

🔧 高级配置

环境变量配置

创建 .env 文件进行环境配置：

# 部署环境标识
REACT_APP_DEPLOY_ENV=production

# 自定义构建选项
VITE_APP_TITLE=Qwerty Learner
VITE_APP_VERSION=1.0.0

自定义词库路径

修改词库加载配置（如需要）：

// src/utils/wordListFetcher.ts
const DICT_BASE_PATH = process.env.NODE_ENV === 'production' 
  ? './dicts/' 
  : '/dicts/';

🐛 常见问题排查

1. 依赖安装失败

问题: yarn install 失败 解决方案:

# 清除缓存
yarn cache clean
# 或使用国内镜像
yarn config set registry https://registry.npmmirror.com

2. 端口冲突

问题: 端口 5173 已被占用 解决方案:

# 指定其他端口
yarn dev --port 3000

3. Tauri 构建错误

问题: Rust 工具链问题 解决方案:

# 更新 Rust
rustup update
# 安装所需组件
rustup target add wasm32-unknown-unknown

4. Docker 构建缓慢

问题: 国内网络环境下载慢 解决方案:

# 在 Dockerfile 中添加镜像源
RUN npm config set registry https://registry.npmmirror.com

📊 性能优化建议

构建优化

# 分析包大小
yarn build --analyze

# 使用代码分割
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          utils: ['lodash', 'dayjs']
        }
      }
    }
  }
})

运行时优化

// 使用 React.memo 优化组件
const MemoizedComponent = React.memo(MyComponent);

// 使用 useMemo 和 useCallback
const expensiveValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
const memoizedCallback = useCallback(() => { doSomething(a, b); }, [a, b]);

🔍 监控与日志

开发环境调试

// 添加性能监控
import { trackEvent } from './utils/trackEvent';

// 关键操作追踪
trackEvent('typing_start', { wordCount: words.length });

生产环境监控

建议集成以下监控工具：

性能监控: Web Vitals, Lighthouse CI
错误追踪: Sentry, Bugsnag
用户行为: Mixpanel, Google Analytics

🎯 部署检查清单

在部署到生产环境前，请确认：

[ ] 所有测试通过 (yarn test:e2e)
[ ] 代码 lint 检查通过 (yarn lint)
[ ] 构建无错误 (yarn build)
[ ] 静态资源路径配置正确
[ ] 环境变量已设置
[ ] CDN 配置完成（如需要）
[ ] 监控工具集成完成

📈 扩展部署方案

云平台部署

平台	部署方式	特点
Vercel	Git 连接自动部署	最适合 React 应用
Netlify	拖拽部署	简单的静态部署
GitHub Pages	Actions 自动部署	免费且简单
阿里云 OSS	CLI 工具部署	国内访问速度快

CI/CD 流水线示例

# GitHub Actions 示例
name: Deploy Qwerty Learner

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: yarn install
    - run: yarn build
    - run: yarn test:e2e
    - uses: vercel/action@v28
      with:
        vercel-token: ${{ secrets.VERCEL_TOKEN }}