wangjia
7849f6e7e5
- 修复 CardTheme → CardThemeData（Flutter 3.41 API 变更） - 修复 finance_screen 缺少 FormDialog import - 修复工具栏 Row overflow（添加横向滚动） - flutter create --platforms=macos,web 生成平台配置 - 添加 docs/dev-setup.md：完整开发环境配置指南 含 Go/Flutter/Docker 安装、已知 macOS 26 兼容问题及解决方案 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
222 lines
4.0 KiB
Markdown
222 lines
4.0 KiB
Markdown
# 开发环境配置指南
|
||
|
||
> 适用平台：macOS（Apple Silicon / Intel）
|
||
|
||
---
|
||
|
||
## 一、必备工具安装
|
||
|
||
### 1. Homebrew（包管理器）
|
||
|
||
```bash
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
```
|
||
|
||
安装后确保 PATH 生效（Apple Silicon 路径为 `/opt/homebrew/bin`）：
|
||
|
||
```bash
|
||
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
---
|
||
|
||
### 2. Go（后端语言）
|
||
|
||
```bash
|
||
brew install go
|
||
```
|
||
|
||
验证：
|
||
|
||
```bash
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
go version # 期望：go1.26.x
|
||
```
|
||
|
||
**注意**：每次运行 Go 命令前须确保 PATH 包含 Homebrew 路径：
|
||
|
||
```bash
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
go build ./...
|
||
```
|
||
|
||
---
|
||
|
||
### 3. Flutter（前端框架）
|
||
|
||
```bash
|
||
brew install --cask flutter
|
||
```
|
||
|
||
验证：
|
||
|
||
```bash
|
||
flutter --version # 期望：Flutter 3.41.x
|
||
```
|
||
|
||
#### 3.1 安装 CocoaPods（macOS 桌面版必须）
|
||
|
||
```bash
|
||
brew install cocoapods
|
||
```
|
||
|
||
#### 3.2 验证全部环境
|
||
|
||
```bash
|
||
flutter doctor
|
||
```
|
||
|
||
期望输出（Android 可以有警告，不影响 macOS/Web 开发）：
|
||
|
||
```
|
||
[✓] Flutter
|
||
[✓] Xcode - develop for iOS and macOS
|
||
[✓] Chrome - develop for the web
|
||
[✓] Connected device
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Docker（本地数据库）
|
||
|
||
```bash
|
||
brew install --cask docker
|
||
```
|
||
|
||
安装后打开 Docker Desktop 应用完成初始化。
|
||
|
||
---
|
||
|
||
### 5. 其他工具（可选）
|
||
|
||
```bash
|
||
brew install git # 版本管理
|
||
brew install --cask vscode # 代码编辑器（推荐安装 Go 和 Flutter 插件）
|
||
```
|
||
|
||
---
|
||
|
||
## 二、项目初始化
|
||
|
||
### 克隆 / 进入项目
|
||
|
||
```bash
|
||
cd /Users/wangjia/code/jiu
|
||
```
|
||
|
||
### 后端依赖
|
||
|
||
```bash
|
||
cd backend
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
go mod download
|
||
```
|
||
|
||
### 前端依赖
|
||
|
||
```bash
|
||
cd client
|
||
flutter pub get
|
||
```
|
||
|
||
---
|
||
|
||
## 三、本地开发启动
|
||
|
||
### 1. 启动数据库
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose up -d
|
||
```
|
||
|
||
- MySQL 端口：`3306`
|
||
- Adminer（数据库管理界面）：http://localhost:8888
|
||
- 服务器：`mysql`，用户：`root`，密码：`password`，数据库：`jiu_db`
|
||
|
||
### 2. 启动后端
|
||
|
||
```bash
|
||
cd backend
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
go run main.go
|
||
```
|
||
|
||
后端启动后监听 `http://localhost:8080`
|
||
|
||
### 3. 启动 Flutter 前端
|
||
|
||
#### Web（推荐开发时使用，稳定）
|
||
|
||
```bash
|
||
cd client
|
||
flutter run -d chrome
|
||
```
|
||
|
||
> macOS 26（beta）下 debug 模式可能有 Flutter 框架断言 bug，加 `--profile` 规避：
|
||
> ```bash
|
||
> flutter run -d chrome --profile
|
||
> ```
|
||
|
||
#### macOS 桌面版
|
||
|
||
```bash
|
||
cd client
|
||
flutter run -d macos --no-enable-impeller
|
||
```
|
||
|
||
> `--no-enable-impeller`：绕过 macOS 26 上 Impeller 着色器编译 OOM 问题
|
||
|
||
---
|
||
|
||
## 四、运行测试
|
||
|
||
```bash
|
||
cd backend
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
go test ./... -cover
|
||
```
|
||
|
||
---
|
||
|
||
## 五、已知问题（macOS 26 beta 环境）
|
||
|
||
| 问题 | 原因 | 解决方式 |
|
||
|------|------|---------|
|
||
| Impeller 着色器编译 exit code -9 | macOS 26 内存压力 + OOM killer | `flutter run --no-enable-impeller` |
|
||
| KeyDownEvent 断言失败（桌面版） | Flutter 3.41 + macOS 26 已知 bug | 改用 Chrome 运行，或等 Flutter 修复 |
|
||
| mouse_tracker 断言失败（debug） | Flutter debug 断言 + hover 事件 | 用 `--profile` 模式运行 |
|
||
|
||
---
|
||
|
||
## 六、环境变量说明
|
||
|
||
敏感配置放在 `~/.env`，通过 `.zshrc` 自动加载（无需手动 source）。
|
||
|
||
后端本地开发配置在 `backend/config/config.yaml`（已被 `.gitignore` 排除）：
|
||
|
||
```yaml
|
||
database:
|
||
dsn: "root:password@tcp(localhost:3306)/jiu_db?charset=utf8mb4&parseTime=True&loc=Local"
|
||
jwt:
|
||
secret: "dev-secret-change-in-prod"
|
||
license:
|
||
hmac_secret: "dev-hmac-secret-change-in-prod"
|
||
```
|
||
|
||
---
|
||
|
||
## 七、flutter doctor 完整检查（参考输出）
|
||
|
||
```
|
||
[✓] Flutter (Channel stable, 3.41.6, on macOS 26.x darwin-arm64)
|
||
[!] Android toolchain ← 不影响 macOS/Web 开发，可忽略
|
||
[✓] Xcode - develop for iOS and macOS (Xcode 26.x)
|
||
[✓] Chrome - develop for the web
|
||
[✓] Connected device (2 available)
|
||
• macOS (desktop)
|
||
• Chrome (web)
|
||
[✓] Network resources
|
||
```
|