本机打包、安装、升级与数据备份

直接回答：可以在当前 Windows 电脑双击 BAT 制作安装包，成功后再自行双击生成的 EXE 安装。设置和恢复草稿不保存在程序安装目录。 但首次需要准备开发工具，打包不是脱离工具链的一键魔法。

1. 四个动作不要混淆

发布到 GitHub 又是另一件事：推送符合版本规则的 tag，触发 CI 测试和多平台安装包工作流。本机 BAT 不会替你提交、打 tag、上传或发布。

2. 最简单的 Windows 打包方法

源码入口：D:\github\apps\Vex-Flutter\build-windows.bat。

1. 准备 .flutter-version 固定的 Flutter SDK，当前为 3.47.7。
2. 安装 Python 3.11+，确认 python 可用。
3. 安装 Visual Studio「使用 C++ 的桌面开发」和 Windows SDK。
4. 在资源管理器双击根目录 build-windows.bat。
5. 等待终端输出 READY，成功后打开产物目录。
6. 关闭正在使用的 Vex，自行双击新生成的安装包。

脚本失败会输出错误与日志位置并保留窗口，不能把“窗口运行过”当作成功。脚本只自动准备固定版 Inno Setup，不替你安装 Flutter / VS / Python，也不自动安装 Vex。

本机打包使用当前工作区内容，包括未提交修改，不会先切换到远端版本；因此安装包成功不代表代码已经提交和推送。2026-10-18 已通过静态分析、423 项 Dart / Flutter 测试、42 项 Python 测试和 Windows 安装包校验；本机预览版编译器首次崩溃中止，改为单并发后重试打包成功，未自动安装产品。

自动执行的步骤

flowchart TD
  A[发现并核对 Flutter 和 Python] --> B[检查 C++ 工具链和版本]
  B --> C[按锁文件取得依赖]
  C --> D[静态分析与全部常规测试]
  D --> E[准备校验过的 Inno Setup]
  E --> F[Flutter Windows Release]
  F --> G[复制所需 VC 运行库并制作安装器]
  G --> H[生成和验证 SHA256]
  H --> I[输出 READY 和安装包目录]

默认包括核心、编辑器、导图、应用四组测试和 Python 脚本契约测试。它不自动执行平台窗口集成测试，也不安装 / 卸载产品来验证；正式发布仍需相应验收和 CI。

结果在哪里

当版本为 0.2.2+4 时：

Vex-Flutter/
├─ artifacts/
│  ├─ local/
│  │  └─ win-x64/
│  │     └─ v0.2.2-build4/
│  │        ├─ Vex-v0.2.2-windows-x64-setup.exe
│  │        └─ Vex-v0.2.2-windows-x64-setup.exe.sha256
│  └─ build-logs/
│     └─ windows-日期-时间.log
└─ apps/vex/build/windows/x64/runner/Release/
   ├─ vex.exe
   ├─ flutter_windows.dll
   ├─ 其他 DLL
   └─ data/

输出目录会随版本和构建号变化。重复构建同版本会更新同名文件；失败时旧文件可能还在，必须以本轮 READY 和日志为准。

0.2.2+4 中，0.2.2 是用户可见版本，4 是构建号，来自 apps/vex/pubspec.yaml；Git 标签通常对应 v0.2.2。独立包的版本属于包 API，可以与最终应用不同；Flutter SDK 版本则是开发工具版本，三者不要混淆。脚本读取现有版本，不自行加版本号。

不要只把 Release 目录里的 vex.exe 单独拷走。 它需要 DLL 和资源。分发给自己或他人时用 setup.exe，安装后的程序不需要对方安装 Flutter、Python 或 Visual Studio。

其他平台也有统一入口

脚本已按平台归类到 scripts/packaging/，各目录的 build.bat / build.sh 是快捷入口；也可在仓库根目录使用统一命令：

例如：python scripts/packaging/build.py win-x64 --check-only。macOS / Linux 将 python 换成 python3。--dry-run 可在任意电脑仅预览配方，不执行构建。各平台本机产物统一保存到 artifacts/local/目标/v版本-build构建号/。

Windows 不能仅靠改目标参数直接构建 Linux / macOS 安装包；脚本会明确检查宿主。Android 正式签名需要另行安全恢复，并设置公开指纹 ANDROID_CERT_SHA256。全部说明见仓库 scripts/packaging/README.md。

3. 找不到工具时怎样配置

脚本按顺序查找 Flutter：命令参数 → VEX_FLUTTER → FLUTTER_ROOT → PATH → 已解析工作区的生成配置。最后一种只是当前电脑的便利，不是换机方案。

在仓库根目录可执行：

.\build-windows.bat -CheckOnly
.\build-windows.bat -Flutter C:\tools\flutter\bin\flutter.bat
.\build-windows.bat -Compiler 'C:\tools\inno\ISCC.exe'
.\build-windows.bat -NoOpenFolder

自动调用可设进程环境变量 VEX_NO_PAUSE=1，BAT 不再等待按键，仍保留失败退出码。双击场景无需设置。

Inno 下载源为官方 GitHub 发布，固定版本 6.7.2；缓存下载也必须匹配固定 SHA-256，再校验发布者签名。无网络又无缓存 / 编译器时会失败，不会悄悄换一个未知版本。

Windows 安装器目前没有 Authenticode 发行证书。SmartScreen 可能警告；.sha256 是完整性校验，不等于 Windows 信任签名。不要因此把安全提醒描述为软件已经获得系统认证。

4. 三个位置一定分开认识

在资源管理器地址栏输入 %APPDATA%\Vex 即可定位用户数据。路径由平台 API 和 Windows 元数据中的产品 Vex 决定；公司字段留空，不增加公司名子目录，也不是硬编码到每台电脑同一个用户名。开发阶段只维护当前目录和数据格式，不扫描或搬迁历史目录，也不主动删除它们。不要把旧配置直接覆盖到当前目录，重要草稿应先保存为 Markdown，并单独备份。

数据文件有什么

文件通常在使用或保存相应功能后产生；没看到某个文件不一定是故障。目录里也可能存在历史版本或其他实现留下的文件，不要仅凭文件名就删除。

内置鸣谢、更新日志随程序打包、只读，不复制成用户可编辑文件。正式笔记则保持用户拥有，不依附内置资源。

5. 安装、升级、卸载会怎样

同一身份的正常升级

当前 Windows 安装采用按用户方式，默认不要求管理员权限。相同用户、相同应用身份和既有安装升级标识下，覆盖安装 / 修复 / 升级替换程序文件，不清理独立用户数据与个人笔记。但“文件还在”不等于“新版一定能读取旧配置”：目前按全新开发维护，不承诺开发版本之间的设置、草稿格式或降级兼容，稳定后再确定迁移策略。已有安装时可能出现维护 / 修复入口，以安装器实际界面为准。

升级前先保存并关闭软件，不要让旧版本进程和新版本同时操作恢复文件。安装器虽然有关闭应用检测，也不能代替你确认工作已保存。

卸载

当前 Windows 安装器不删除上述应用支持目录，正常卸载也不删除你另行保存的 .md。因此卸载后重装可能读到原有偏好。想清空设置是单独的用户数据操作，应该先备份，不应混入普通卸载。

不能做的保证

• 更换应用包标识、公司 / 产品元数据、平台签名，可能成为新应用身份；旧设置和草稿不会自动迁移。
• 换 Windows 用户不共享同一用户目录。
• 新版本的数据格式可能不兼容旧版本；不要默认支持任意降级。
• 磁盘损坏、断电、清理软件和人为删除仍可能导致数据丢失。
• Android / iOS 卸载通常删除应用沙箱，不能套用 Windows 卸载保留规则。

所以答案是：程序与数据已经分离，安装器不清理个人数据；开发版本仍不保证旧配置可用，更新前要保存文档并独立备份。

6. 一份可执行的备份清单

• 在 Vex 中把重要草稿保存成真正的 .md。
• 关闭所有 Vex 窗口，避免备份时配置还在变化。
• 备份整个笔记目录，包含图片和其他相对路径附件。
• 单独备份 %APPDATA%\Vex，包含设置和恢复数据。
• 将含令牌的配置备份加密，不发到公开仓库或群聊。
• 开发者另行加密备份 .signing、keystore 和配套信息。
• 记录应用版本、系统和备份日期。
• 在另一位置检查文件确实存在、能打开，而不是只看到一个空文件夹。

还原用户数据前关闭应用；先保留新电脑原数据副本，再还原同身份、相近版本的数据。对正式笔记，可先在 Vex 里直接打开验证，不必把笔记复制进配置目录。

7. 换电脑到底要带哪些

8. 其他平台与 GitHub 发布

当前发布配方目标为 Windows EXE、macOS 通用 DMG、Linux x64 / ARM64 DEB、Android 三架构正式签名 APK，共七个安装包及各自校验文件。以具体 GitHub Actions 成功结果和 Release 实际附件为准。

Windows 本机 BAT 只产 Windows x64 包。macOS / iOS 构建需要 macOS 工具链；Android、Linux 也有各自配方，不能靠同一个 Windows BAT 跨编全部原生安装包。iOS 和 HarmonyOS 按已确认决定暂缓发布可安装包，待证书和适配条件具备再补。

正式自动发布入口是 .github/workflows/release.yml；细则见源码仓库 docs/安装包与自动发布.md。学习或本机试装不必立刻发版，也不要为了测试移动已有 tag。

下一篇：Markdown 阅读练习。