14 KiB
2026-11-19 工作日志
GC 项目 Flutter 1.1.1 编译环境配置
项目结构关键发现
- 仓库有两个远程:
origin(Avalonia 版,分支main)和origin2(Flutter 版,分支origin2/main,tag1.1.1)。 - 用户口中的"C#+Flutter 项目"指 origin2/main:
GC-UI/是前后端分离实现——Flutter 前端(GC-UI/frontend/)+ .NET 8 后端(GC-UI/backend/GC.UI.Server/)。模型窗口仍由后端用 Avalonia 承载(契约不可变)。 - 当前
main分支是纯 Avalonia 版,无 Flutter 代码。最初误判"没有 Flutter",实际在另一远程分支。
分支操作
- 原
main有未提交改动(8 个文件,version.json 从 1.0.7 手改成 1.1.1),已 stash 到stash@{0}(message:backup-before-flutter-switch-20261119)。 - 已新建本地分支
flutter-1.1.1跟踪origin2/main,HEAD 在 tag1.1.1(commit 3c74eff)。
Flutter 环境(已完成)
- 工程锁定 Flutter 3.24.5(Dart 3.5.4),依据是
GC-UI/frontend/.metadata的 revisiondec2ee5c1f98f8e84a7d5380c05eb8a3d0a81668,与官方 release hash 一致。 - SDK 安装在
/Users/lixi/development/flutter,zip 校验 sha256ca9624a6de7a1a8962f2f0a3e2a57b16434ca34f1137b8d9dc68c5ca1f187133。 - 国内镜像(快 100 倍,8MB/s):
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn、PUB_HOSTED_URL=https://pub.flutter-io.cn。 - 已把 PATH 和两个镜像变量写入
~/.zshrc。 flutter pub get成功,flutter analyze零问题(代码本身健康)。- 注意:Flutter 构建命令需在无沙箱模式下运行(需写 SDK 缓存目录
.pub-preload-cache)。
编译阻塞(待用户处理)
- 目标 macOS 版,但本机只有 Command Line Tools,无完整 Xcode(
xcodebuild不存在)。 flutter build macos --release实测报错 exit 72:xcrun: error: unable to find utility "xcodebuild"。- App Store 无 Apple ID 登录态(MobileMeAccounts / 钥匙串均无凭据),命令行无法无人值守安装 Xcode。
- 用户选择:自己手动在 App Store 登录并安装 Xcode,装完后再继续
flutter build macos。 - 备选方案(用户未选):本机可用
buildsh/cross/build-ui-win-cross.sh走 mingw-w64 + wine 交叉编译 Windows 版(需brew install mingw-w64 cmake ninja+brew install --cask wine-stable),Rosetta 2 已安装。
编译完成(Xcode 27.2 装好后)
用户手动装好 Xcode 27.2(/Applications/Xcode.app,xcode-select 已指向)。编译过程连破 3 个新 Xcode 兼容问题:
- 部署目标过低:
macos/Runner.xcodeproj/project.pbxproj三处MACOSX_DEPLOYMENT_TARGET = 10.14→ 改为12.0(Xcode 27 最低支持 12.0)。这是对工程文件的持久化改动。 - lipo -verify_arch 参数解析变更:Flutter 3.24.5 的
packages/flutter_tools/lib/src/build_system/targets/macos.dart一次性传多个架构给-verify_arch,Xcode 27 的 lipo 报 "requires exactly one input file"。改为逐个架构分别验证。改后需删bin/cache/flutter_tools.stamp强制重建 snapshot 才生效。 - 假符号链接:解压 Flutter SDK 时沙箱把
.framework里的符号链接写成文本文件路径(内容是Versions/Current/...),导致 SwiftPM 报Unable to resolve module 'FlutterMacOS'。按「先 Versions/Current→A,再顶层 4 个链接」顺序修复,共 19 个(SDK artifacts 15 + build 目录 4)。修复脚本思路见/tmp/fix2.sh(临时)。
产物:GC-UI/frontend/build/macos/Build/Products/Release/GC-UI.app(38MB,版本 1.1.1,universal x86_64+arm64,adhoc 签名,bundle id com.morris.gc.gcUi)。
交付 zip:dist/GC-UI-1.1.1-mac-universal.zip(16MB,sha256 55f40c146e86cfed3adc1f02a72ab89944dd81ba8e9c8ba6cf929f7061573db5)。
注意:这是 Flutter 前端外壳,需 .NET 后端(GC.UI.Server / GC-BOOT 进程内托管)配合才能完整工作。完整发布包 GC.app 需走 build.sh build,但该流程强制走 Windows 交叉编译(wine/mingw,本机装不了,Homebrew 被沙箱拦截),故未跑完整发布。
"打开即连好"完整发布包(用户反馈单独 GC-UI.app 报"无法连接后端")
根因:Flutter 前端不含后端,靠 GC_UI_PORT 环境变量 / .GC/ui-backend.json 发现后端。正统入口是 GC-BOOT(产物 GC):FlutterShell.TryRun 在进程内起后端 → 选端口 → 拉起 GC-UI.app/Contents/MacOS/GC-UI 并传入 GC_UI_PORT → 前端自动连上。单独双击 GC-UI.app 必然连不上。
手动只构建 macOS 完整包(绕开装不了的 wine/mingw):
dotnet publish GC-BOOT/GC-BOOT.csproj -c Release -r osx-arm64 --self-contained -p:... -o dist/mac-arm64(GC-BOOT.csproj 已把后端作库引用,FrameworkReference Microsoft.AspNetCore.App,一个 exe 够用)- 同样 publish
GC-SAVEDOG(裁剪) - 复制 GC-UI.app 到 dist/mac-arm64
- 组装 GC.app:Info.plist(版本 1.1.1)+ Contents/MacOS 放 GC/GC.UI.Server.runtimeconfig.json/GC-UI.app,SAVEDOG 收进
.GC/bin,iconutil 从 icon-1024.png 生成 AppIcon.icns ditto -c -k --sequesterRsrc --keepParent打包
验证通过:open GC.app 后用 curl 查 http://127.0.0.1:17890/api/health 返回 {"ok":true,"version":"1.1.1","platform":"osx-arm64"};frontend 进程 GC-UI 在跑;models/settings/about API 全部正常。测试完已 pkill 并清掉 .GC 运行数据。
最终交付:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 3bb4101fee9588b1a3b73dcf2e65bc081b83220e5fbbe18a433ee2af8ccfb5e3),解压得 GC.app,双击即自动连好后端。旧的 dist/GC-UI-1.1.1-mac-universal.zip 只是纯前端,已被取代。
注意:dotnet publish 的 -o dist/mac-arm64 不会清旧文件;rm -rf dist/mac-arm64 会触发批量删除保护(156 文件)。发布包数据目录落在 dist/mac-arm64/.GC(AppPaths 回退逻辑),启动器日志里 SAVEDOG 显示"未找到"是因为它找的是同级而非 .GC/bin,不影响主流程。
真正根因:App Sandbox 缺 network.client(用户第二次反馈仍连不上)
上面的"验证通过"是假阳性:只 curl 了后端(后端在沙箱外,当然正常),从没让前端真发请求。前端报"无法连接后端(baseUrl)"是 api_client.dart:428 的 ApiException。
真因:GC-UI/frontend/macos/Runner/Release.entitlements 只开了 com.apple.security.app-sandbox=true,没有 com.apple.security.network.client。沙箱内进程向 127.0.0.1:17890 发起出站 HTTP 会被内核拒绝(EPERM),所以发布版前端连不上;DebugProfile.entitlements 有 network.server 所以开发时正常,掩盖了问题。用 codesign -d --entitlements :- GC-UI.app 可确认签名里只有 app-sandbox。
修复:给 Release.entitlements 加 network.client + network.server → 重新 flutter build macos --release(新签名自动嵌入)→ 替换 GC.app 内 GC-UI.app → 重打包。
这次验证到位:open GC.app 后 lsof -nP -a -p <前端PID> -iTCP 显示 GC-UI ... TCP 127.0.0.1:60082->127.0.0.1:17890 (ESTABLISHED)——前端真连上了。这才是"打开即连好"的硬证据。
最终交付覆盖更新:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 2b0f4c25ce4e52edf18a45ceb2fe2f91612757db5589f346ffd984665cab5172),包内前端签名已含 network.client/server。
教训:验证桌面端"连后端"必须看前端进程的网络连接(lsof),不能只 curl 后端。无 GUI 会话时 screencapture/AppleScript 不可用。
恢复用户改动
回到 main 后执行 git stash pop 恢复 stash@{0} 的 8 个文件改动。
当前 checkout 分支:flutter-1.1.1(跟踪 origin2/main,tag 1.1.1)。
提交 PR 到 xhmcl(Gitea 28.1.0,git.xhmcl.com/Morris/GC)
分支 fix/macos-release-sandbox-network(commit 3efdf74),只含本次修复两文件:Release.entitlements、project.pbxproj。
严格排除了干扰项:model/contour-map/*(他人地貌改动)、pubspec.lock(配国内镜像 pub get 的副作用,不能提交)、未跟踪的 mp4/js/html 等。
PR #28:Morris/GC#28 (base main,state open,mergeable=true,+7/−3,2 files)。
凭据/接口要点(踩坑记录):
- 该实例 git 协议与 API 认证分离。
gdt_...是 git 凭据(当密码用可 push),但调 API 全部 401(Authorization: token/Bearer、X-Token、PRIVATE-TOKEN、query 都试过)。 - 建 PR 必须用账号登录密码做 basic auth:
curl -u 'Morris:<密码>' -X POST .../api/v1/repos/Morris/GC/pulls -d @body.json,返回 201。 - push 时若报 "unable to get credential storage lock: File exists",用
git -c credential.helper= push+GIT_ASKPASS脚本绕过;其实首次已推成功,是误报。 - 临时凭据文件(netrc/askpass/pr.json)用完即删,不落盘留存。
- 注意:本机无图形会话时 screencapture/AppleScript 不可用;验证"前端连后端"必须用
lsof -nP -a -p <PID> -iTCP看 ESTABLISHED。
模型无法启动 + 后端崩溃(PR #29)
根因:macOS 的 AppKit 要求 NSApplication 在主线程。Flutter 模式下 FlutterShell 用 ui.WaitForExit() 占住主线程,而 AvaloniaHost 在 new Thread(...) 副线程里跑 StartWithClassicDesktopLifetime。点「启动模型」时模型窗口在副线程触碰 AppKit → 进程级崩溃,后端随之消失(表现为"无法启动模型"+"后端容易崩溃")。纯 Avalonia 版不受影响,只在 Flutter 打包模式暴露。
修复(4 文件,+114/−51):
AvaloniaHost:新增RunOnCurrentThread()/Shutdown(),EnsureStartedAsync()改为只等_ready,不再自建线程。BackendServer.Start(args, port, out AvaloniaHost)重载(out 参数不能在 lambda 里用,内部用局部host)。FlutterShell:前端拉起后在主线程跑 Avalonia 事件循环,ui.Exited时后台Shutdown();Avalonia 不可用时退化WaitForExit()。Program.cs:app.StartAsync()后主线程跑 Avalonia,失败则WaitForShutdown()(需using Microsoft.Extensions.Hosting)。
验证:/api/health → uiAvailable:true;前端 ESTABLISHED →17890;POST launch → HTTP 200 {"ok":true,"message":"已启动模型 contour-map"};启动后后端存活。
交付:dist/mac-arm64/GC-1.1.1-mac-arm64.zip(72MB,sha256 4b3978eab5cb8fba4e97a3a623cb532080b9e0e24dd6f3e28e69440966c510bb)。
PR #29:Morris/GC#29
坑:dist/mac-arm64/GC.app 在清理 .GC 时被误删过;可从 /tmp/gc-fresh-test/GC.app 取 GC-SAVEDOG 与结构,配合 /tmp/gc-new/GC(publish 产物)+ build 目录新前端重建。组装脚本见上面的"打开即连好完整发布包"步骤。
contour-map 模型重写(对照加密 HTML 课件移植)
背景:用户提供的 ~/Downloads/等高线及地形部位演示.html(79MB)是授权壳 + AES-256-GCM + gzip 的课件,内含 Three.js 版五大地貌演示。已在本地用 node 复现解密(key = 两数组异或,AAD QLAB|contour-landform-reading|...),还原出 83MB 内部课件;其内容为「10 张内嵌 PNG + 切割视频 + 标注层」,并非可交互 3D。按用户要求改为在 model/contour-map 用 C#/Avalonia 重写。
改动文件(均在 model/contour-map/src/):
TerrainField.cs:新增LandformKind(Peak/Ridge/Valley/Saddle/Cliff)与五个高度场生成器。要点是地形要宽阔(穹状山体、宽脊、V 形谷、双峰垭口、台地陡崖),半径过小会变成“尖锥/薄墙”。ContourView.cs:重写为可交互 3D(拖动旋转、滚轮缩放),四步实验(切割/成线/投影/判坡),俯视/立体切换,自动取景UpdateCamera(按包围盒八点投影铺满画布),法线光照,裙边侧壁,分层设色在 3D 用ColorForHeightSmooth平滑过渡、俯视仍用硬分档。ContourPage.cs:地貌标签移到画布上方(WrapPanel,窄屏自动换行);右侧栏 344px,<980px 自动隐藏;四步流程/观察面板/判读要点;底部播放、重置、视图切换、上色、实时读数;空格与 1–5 快捷键;全屏。DefaultTexts.cs:90 个键,中英各一套。ContourMapRuntime.cs:LoadTexts改为「内置默认 + i18n/*.json 覆盖」,之前完全忽略语言包。- 清单
contour-map.json版本 1.1 → 1.2;help.json同步新交互。
修掉的真实 Bug:
ExtractContour的Chain()只向尾部延伸,一条等高线被切成大量短链 → 3D 里显示成虚线等高线。改为端点索引 + 双向延伸后,每层只剩 1 条 300+ 点的完整曲线。SlopeAt固定除以 450,导致山体坡度全饱和为 1(整片红),“疏密判坡”失效。改为按span*2.6自适应归一化。- 切割步骤原本只是叠一张半透明板,山尖仍在。改为把高度场压到切面
min(h, lv),得到真实截面,并用ExtractContour(lv)精确求交线。 - 切割时山峰标注悬在切面上方 → 高于切面的山峰不再标注。
性能:62×62 面片 + 画刷颜色缓存,1440×900 离屏单帧约 35ms(≈28fps),可接受。
验证:dotnet build 0 警告 0 错误;dotnet run --project model/_engine/PreviewGen 全模型离屏渲染通过并生成封面;自建 /tmp/ccheck 全尺寸渲染器逐状态出图核对(默认/俯视/五地貌/四步/中间帧)。
交付:PR #30 Morris/GC#30(feat/contour-map-rewrite → main,12 文件 +1903/-600,基于最新 main 单提交)。提交 PR 时注意:本地 flutter-1.1.1 落后 origin2/main 4 个提交,需先 stash 改动、从 origin2/main 建分支再 pop,否则 PR 会带上 48 个无关提交;gitcode(origin) 的 main 更旧且仍是 NeoRF.* 命名空间,不宜作为 PR 目标。推送用 GIT_ASKPASS 临时脚本传凭据,用完即删,不写 remote URL。