manta/gofaster/app/DEVELOPMENT.md

# GoFaster 开发指南

## 解决Cursor终端中文乱码问题

由于PowerShell的编码问题，在运行`npm run dev`时可能会出现中文乱码。我们提供了多种解决方案：

### 方案1：使用稳定开发脚本（推荐）

```bash
npm run dev:stable
```

这个命令会：
- 自动设置控制台编码为UTF-8
- 设置正确的环境变量
- 构建Vue应用
- 使用稳定的Electron配置启动
- 包含错误处理和重试机制

### 方案2：使用批处理文件

```bash
npm run dev:bat
```

这个命令会：
- 自动设置控制台编码为UTF-8
- 设置环境变量
- 构建并启动应用

### 方案3：使用PowerShell脚本

```bash
npm run dev:ps
```

这个命令会：
- 设置PowerShell编码为UTF-8
- 设置环境变量
- 构建并启动应用

### 方案4：分步执行

如果上述方案仍有问题，可以分步执行：

```bash
# 第一步：构建Vue应用
npm run build:vue

# 第二步：启动Electron
electron .
```

## 解决热加载问题

### 常见热加载错误

1. **JavaScript注入失败**：`An object could not be cloned`
   - 原因：注入的JavaScript包含无法序列化的对象
   - 解决：使用`npm run dev:stable`启动

2. **页面重载失败**：频繁的文件变化导致重载问题
   - 解决：已添加500ms防抖机制

3. **渲染进程崩溃**：开发环境不稳定
   - 解决：使用稳定的Electron启动参数

### 稳定开发配置

`dev:stable`脚本包含以下稳定配置：
- `--disable-gpu`：禁用GPU加速，提高稳定性
- `--disable-software-rasterizer`：禁用软件光栅化
- `--disable-dev-shm-usage`：禁用开发共享内存

## 环境变量说明

- `VUE_CLI_BABEL_TRANSPILE_MODULES=false`: 禁用Babel模块转译
- `VUE_CLI_MODERN_BUILD=false`: 禁用现代构建模式
- `NODE_ENV=development`: 设置开发环境

## 故障排除

### 如果仍然出现乱码：

1. **检查PowerShell版本**：确保使用PowerShell 5.1或更高版本
2. **设置执行策略**：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
3. **使用Windows Terminal**：Windows Terminal对UTF-8支持更好
4. **检查系统区域设置**：确保系统支持UTF-8

### 如果热加载失败：

1. **使用稳定脚本**：`npm run dev:stable`
2. **清理构建缓存**：删除`dist`目录后重新构建
3. **检查文件权限**：确保有足够的文件读写权限
4. **重启开发环境**：完全关闭后重新启动

### 如果构建失败：

1. **清理缓存**：`npm run clean` 或删除 `node_modules` 和 `dist` 目录
2. **重新安装依赖**：`npm install`
3. **检查Node.js版本**：确保使用Node.js 16或更高版本

## 开发流程

1. 使用 `npm run dev:stable` 启动开发环境（推荐）
2. 修改代码后，应用会自动重新加载
3. 使用 `Ctrl+C` 停止开发服务器

## 注意事项

- 所有控制台输出都已改为英文，避免编码问题
- 应用界面仍然支持中文显示
- 字体配置已优化，确保中文正常显示
- 热加载已优化，包含错误处理和防抖机制
- 提供多种启动方式，适应不同环境需求