Files

T

wangjia 7849f6e7e5 chore: 添加 macOS/Web 平台支持 + 修复编译错误 + 开发环境文档

- 修复 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>

2026-04-04 13:36:39 +08:00

4.0 KiB

Raw Blame History

开发环境配置指南

适用平台：macOS（Apple Silicon / Intel）

一、必备工具安装

1. Homebrew（包管理器）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装后确保 PATH 生效（Apple Silicon 路径为 /opt/homebrew/bin）：

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Go（后端语言）

brew install go

验证：

export PATH="/opt/homebrew/bin:$PATH"
go version   # 期望：go1.26.x

注意：每次运行 Go 命令前须确保 PATH 包含 Homebrew 路径：

export PATH="/opt/homebrew/bin:$PATH"
go build ./...

3. Flutter（前端框架）

brew install --cask flutter

验证：

flutter --version   # 期望：Flutter 3.41.x

3.1 安装 CocoaPods（macOS 桌面版必须）

brew install cocoapods

3.2 验证全部环境

flutter doctor

期望输出（Android 可以有警告，不影响 macOS/Web 开发）：

[✓] Flutter
[✓] Xcode - develop for iOS and macOS
[✓] Chrome - develop for the web
[✓] Connected device

4. Docker（本地数据库）

brew install --cask docker

安装后打开 Docker Desktop 应用完成初始化。

5. 其他工具（可选）

brew install git          # 版本管理
brew install --cask vscode  # 代码编辑器（推荐安装 Go 和 Flutter 插件）

二、项目初始化

克隆 / 进入项目

cd /Users/wangjia/code/jiu

后端依赖

cd backend
export PATH="/opt/homebrew/bin:$PATH"
go mod download

前端依赖

cd client
flutter pub get

三、本地开发启动

1. 启动数据库

cd deploy
docker compose up -d

MySQL 端口：3306
Adminer（数据库管理界面）：http://localhost:8888
- 服务器：mysql，用户：root，密码：password，数据库：jiu_db

2. 启动后端

cd backend
export PATH="/opt/homebrew/bin:$PATH"
go run main.go

后端启动后监听 http://localhost:8080

3. 启动 Flutter 前端

Web（推荐开发时使用，稳定）

cd client
flutter run -d chrome

macOS 26（beta）下 debug 模式可能有 Flutter 框架断言 bug，加 --profile 规避：
flutter run -d chrome --profile

macOS 桌面版

cd client
flutter run -d macos --no-enable-impeller

--no-enable-impeller：绕过 macOS 26 上 Impeller 着色器编译 OOM 问题

四、运行测试

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 排除）：

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

4.0 KiB Raw Blame History Unescape Escape