尧图网站建设 
在 Windows 上构建 Actual使用 Git Bash 搭建本地开发环境的完整指南【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 是一款 local-first本地优先的个人财务管理应用其仓库采用 Yarn 4 workspaces 管理的 monorepo 结构。本项目的大多数构建脚本都是 bash 脚本无法在 Windows 的命令提示符或 PowerShell 中直接执行。本文基于官方 Windows 构建指南结合仓库源码与配置系统讲解如何在 Windows 上通过 Git Bash 完成 Actual 的浏览器版与 Electron 桌面版的本地构建与调试并逐条解析高频报错rsync: command not found、符号链接权限错误等的根因与解决方案。为什么 Windows 上需要 Git Bash进入仓库根目录即可看到构建入口都是 bash 脚本。例如 bin/package-browser 和 bin/package-electron 以#!/bin/bash -e开头内部大量使用pushd/popd、$#参数解析、$RELEASE环境变量等 bash 特性Windows 原生 shell 无法直接解析。再看根目录 package.json 中的脚本定义build:browser: ./bin/package-browser, build:desktop: ./bin/package-electron, rebuild-electron: ./node_modules/.bin/electron-rebuild -m ./packages/desktop-electron -o better-sqlite3,bcrypt,argon2 --build-from-source -f./bin/package-*这类相对路径脚本只能由 bash 解释执行。因此官方给出的解决思路是安装 Git for Windows 自带的 Git Bash把所有构建命令放进 bash 环境中执行从而获得与 Linux/macOS 一致的脚本运行环境。第一步准备构建环境按照官方文档构建前需要依次完成以下准备工作对应原文档 Steps 1–4安装 Git Git Bash for Windows从 Git 官方下载页获取安装包安装完成后即可在开始菜单中找到 Git Bash。这是整个方案的核心前置条件。激活 Windows 开发者模式在 Windows 设置的开发者选项中启用。此步骤与后文提到的符号链接权限问题直接相关详见常见错误排查一节。安装 Node.js v22.x 或更高版本仓库 package.json 的engines字段明确要求node 22.18.0、yarn ^4.9.1。在 development-setup.md 中还有一个 Windows 专属提示安装 Node.js 时务必在Tools for Native Modules页面勾选Automatically install the necessary tools——这是因为项目依赖better-sqlite3等原生模块需要本机编译工具链Python、Visual Studio Build Tools。克隆本仓库将 Actual 仓库克隆到本地。版本说明与其它平台不同Windows 构建对版本边界更敏感。安装完成后可用node --version、yarn --version校验具体版本要求以仓库package.json的engines为准当前为 Node ≥ 22.18.0、Yarn ^4.9.1。第二步以管理员身份启动 Git Bash 并安装依赖官方文档明确要求以管理员身份Run as administrator运行 Git Bash然后执行cd /path/to/actual yarn installyarn install会按 Yarn workspaces 配置为packages/*下所有子包如loot-core、desktop-client、desktop-electron、sync-server等统一安装依赖。之所以强制管理员权限是因为构建流程需要创建符号链接见下文错误章节非管理员环境下该操作会被系统拒绝。第三步启动浏览器开发版本依赖安装完成后仍在 Git Bash 中运行yarn start:browser对应根 package.json 中的定义该命令会通过npm-run-all并行启动start:browser-*与start:service-plugins多个子任务包括前端开发服务器与插件服务。启动成功后在浏览器中打开http://localhost:3001即可看到 Actual 的开发界面。这也是 development-setup.md 中提到的统一开发入口yarn start根脚本中start: yarn start:browser所指向的命令。第四步构建 Electron 桌面应用如果目标是本地运行桌面版官方文档给出的步骤是先完成上文步骤 1–6即环境准备 yarn install运行yarn start。这里需要留意官方文档记录的两种情况如果报错提示bundle.desktop.js相关错误先按CtrlC中断然后重新运行yarn start。这通常是因为 Electron 主进程的产物尚未就绪首次构建时的时序问题。如果 Electron 启动时报错运行yarn rebuild-electron然后重新执行yarn start。为什么需要yarn rebuild-electronElectron 内置的 Node.js 与系统安装的 Node.js 版本不同因此better-sqlite3、bcrypt、argon2这些原生模块必须针对 Electron 的 ABI 重新编译。根 package.json 中的rebuild-electron脚本会调用electron-rebuild并显式指定这三个模块--build-from-source -f强制从源码构建./node_modules/.bin/electron-rebuild -m ./packages/desktop-electron -o better-sqlite3,bcrypt,argon2 --build-from-source -f这与 troubleshooting.md 中Native module build failures (better-sqlite3)一节给出的处理方式一致。Windows 上若此前未勾选 Node 安装器中的Automatically install the necessary tools这一步极可能因缺少编译工具链而失败需要回头补装 Visual Studio Build Tools。desktop-electron工作区自身的脚本见 packages/desktop-electron/package.json也印证了构建链路watch脚本通过cross-env设置ACTUAL_DOCUMENT_DIR、ACTUAL_DATA_DIR后启动 Electronbuild则执行tsgo yarn copy-static-assets再由electron-builder打包。生成 Windows 安装包如果需要产出可分发的 Windows 安装程序可运行yarn build:desktop。该命令最终由 bin/package-electron 驱动依次构建 crdt、plugins-service、core、web、sync-server 等子包最后在packages/desktop-electron目录下调用electron-builder。从 packages/desktop-electron/package.json 的build.win配置可见Windows 目标支持appxWindows 应用商店格式与nsis经典安装向导两种格式产物按actual-windows-${arch}命名覆盖ia32、x64、arm64三种架构。需要特别指出的是这条完整链路对 bash 依赖程度更高正是前文强调全程使用 Git Bash的原因。常见错误排查错误一rsync: command not found现象构建过程中 bash 找不到rsync命令。原因项目构建脚本例如资源同步环节依赖rsync但 Git for Windows 默认并未携带该二进制。解决为 Git Bash 手动安装rsync可执行文件。网上有社区整理的安装方法核心思路是把编译好的rsync.exe放入 Git 安装目录下的usr/bin或 Git Bash 的 PATH 覆盖目录随后重新打开 Git Bash 验证rsync --version可用即可继续构建。注意版本需与 Git Bash 的运行环境通常为 MSYS2/MinGW兼容。错误二ln: failed to create symbolic link ../../desktop-client/public/kcab: Operation not permitted现象构建时创建符号链接失败报Operation not permitted。原因构建流程需要在desktop-client/public下创建符号链接目标名为kcab。在 Windows 上创建符号链接需要开发者模式或管理员权限普通权限的 shell 会被系统拒绝。解决官方文档给出的明确做法是——以管理员身份运行 Git Bash。如果已经以管理员身份运行仍失败请检查开发者模式是否已启用对应上文准备步骤 2该模式允许非提升进程创建符号链接。两步都满足后重试即可。更多排查方向围绕 Windows 构建仓库的 troubleshooting.md 还提供了几条与本主题直接相关的建议可一并参考构建产物残留删除packages/*/dist、packages/*/lib-dist、packages/*/build后重新yarn install版本校验node --version需 ≥ 22yarn --version需匹配 ^4.9.1原生模块失败Windows 下确认已安装 Python 与 Visual Studio Build Tools必要时执行yarn rebuild-electronElectron 场景或yarn workspace actual-app/core rebuildNode 场景。小结在 Windows 上构建 Actual 的关键可以归纳为一句话所有构建命令一律在管理员身份的 Git Bash 中执行。在此基础上依次完成环境准备、yarn install、yarn start:browser浏览器版或yarn start 按需yarn rebuild-electron桌面版并针对rsync缺失与符号链接权限两个高频问题提前做好准备即可获得与 Linux/macOS 一致的开发体验。进一步的环境搭建细节可参考 development-setup.md完整排查清单见 troubleshooting.md。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Windows 上构建 Actual：使用 Git Bash 搭建本地开发环境的完整指南
在 Windows 上构建 Actual使用 Git Bash 搭建本地开发环境的完整指南【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 是一款 local-first本地优先的个人财务管理应用其仓库采用 Yarn 4 workspaces 管理的 monorepo 结构。本项目的大多数构建脚本都是 bash 脚本无法在 Windows 的命令提示符或 PowerShell 中直接执行。本文基于官方 Windows 构建指南结合仓库源码与配置系统讲解如何在 Windows 上通过 Git Bash 完成 Actual 的浏览器版与 Electron 桌面版的本地构建与调试并逐条解析高频报错rsync: command not found、符号链接权限错误等的根因与解决方案。为什么 Windows 上需要 Git Bash进入仓库根目录即可看到构建入口都是 bash 脚本。例如 bin/package-browser 和 bin/package-electron 以#!/bin/bash -e开头内部大量使用pushd/popd、$#参数解析、$RELEASE环境变量等 bash 特性Windows 原生 shell 无法直接解析。再看根目录 package.json 中的脚本定义build:browser: ./bin/package-browser, build:desktop: ./bin/package-electron, rebuild-electron: ./node_modules/.bin/electron-rebuild -m ./packages/desktop-electron -o better-sqlite3,bcrypt,argon2 --build-from-source -f./bin/package-*这类相对路径脚本只能由 bash 解释执行。因此官方给出的解决思路是安装 Git for Windows 自带的 Git Bash把所有构建命令放进 bash 环境中执行从而获得与 Linux/macOS 一致的脚本运行环境。第一步准备构建环境按照官方文档构建前需要依次完成以下准备工作对应原文档 Steps 1–4安装 Git Git Bash for Windows从 Git 官方下载页获取安装包安装完成后即可在开始菜单中找到 Git Bash。这是整个方案的核心前置条件。激活 Windows 开发者模式在 Windows 设置的开发者选项中启用。此步骤与后文提到的符号链接权限问题直接相关详见常见错误排查一节。安装 Node.js v22.x 或更高版本仓库 package.json 的engines字段明确要求node 22.18.0、yarn ^4.9.1。在 development-setup.md 中还有一个 Windows 专属提示安装 Node.js 时务必在Tools for Native Modules页面勾选Automatically install the necessary tools——这是因为项目依赖better-sqlite3等原生模块需要本机编译工具链Python、Visual Studio Build Tools。克隆本仓库将 Actual 仓库克隆到本地。版本说明与其它平台不同Windows 构建对版本边界更敏感。安装完成后可用node --version、yarn --version校验具体版本要求以仓库package.json的engines为准当前为 Node ≥ 22.18.0、Yarn ^4.9.1。第二步以管理员身份启动 Git Bash 并安装依赖官方文档明确要求以管理员身份Run as administrator运行 Git Bash然后执行cd /path/to/actual yarn installyarn install会按 Yarn workspaces 配置为packages/*下所有子包如loot-core、desktop-client、desktop-electron、sync-server等统一安装依赖。之所以强制管理员权限是因为构建流程需要创建符号链接见下文错误章节非管理员环境下该操作会被系统拒绝。第三步启动浏览器开发版本依赖安装完成后仍在 Git Bash 中运行yarn start:browser对应根 package.json 中的定义该命令会通过npm-run-all并行启动start:browser-*与start:service-plugins多个子任务包括前端开发服务器与插件服务。启动成功后在浏览器中打开http://localhost:3001即可看到 Actual 的开发界面。这也是 development-setup.md 中提到的统一开发入口yarn start根脚本中start: yarn start:browser所指向的命令。第四步构建 Electron 桌面应用如果目标是本地运行桌面版官方文档给出的步骤是先完成上文步骤 1–6即环境准备 yarn install运行yarn start。这里需要留意官方文档记录的两种情况如果报错提示bundle.desktop.js相关错误先按CtrlC中断然后重新运行yarn start。这通常是因为 Electron 主进程的产物尚未就绪首次构建时的时序问题。如果 Electron 启动时报错运行yarn rebuild-electron然后重新执行yarn start。为什么需要yarn rebuild-electronElectron 内置的 Node.js 与系统安装的 Node.js 版本不同因此better-sqlite3、bcrypt、argon2这些原生模块必须针对 Electron 的 ABI 重新编译。根 package.json 中的rebuild-electron脚本会调用electron-rebuild并显式指定这三个模块--build-from-source -f强制从源码构建./node_modules/.bin/electron-rebuild -m ./packages/desktop-electron -o better-sqlite3,bcrypt,argon2 --build-from-source -f这与 troubleshooting.md 中Native module build failures (better-sqlite3)一节给出的处理方式一致。Windows 上若此前未勾选 Node 安装器中的Automatically install the necessary tools这一步极可能因缺少编译工具链而失败需要回头补装 Visual Studio Build Tools。desktop-electron工作区自身的脚本见 packages/desktop-electron/package.json也印证了构建链路watch脚本通过cross-env设置ACTUAL_DOCUMENT_DIR、ACTUAL_DATA_DIR后启动 Electronbuild则执行tsgo yarn copy-static-assets再由electron-builder打包。生成 Windows 安装包如果需要产出可分发的 Windows 安装程序可运行yarn build:desktop。该命令最终由 bin/package-electron 驱动依次构建 crdt、plugins-service、core、web、sync-server 等子包最后在packages/desktop-electron目录下调用electron-builder。从 packages/desktop-electron/package.json 的build.win配置可见Windows 目标支持appxWindows 应用商店格式与nsis经典安装向导两种格式产物按actual-windows-${arch}命名覆盖ia32、x64、arm64三种架构。需要特别指出的是这条完整链路对 bash 依赖程度更高正是前文强调全程使用 Git Bash的原因。常见错误排查错误一rsync: command not found现象构建过程中 bash 找不到rsync命令。原因项目构建脚本例如资源同步环节依赖rsync但 Git for Windows 默认并未携带该二进制。解决为 Git Bash 手动安装rsync可执行文件。网上有社区整理的安装方法核心思路是把编译好的rsync.exe放入 Git 安装目录下的usr/bin或 Git Bash 的 PATH 覆盖目录随后重新打开 Git Bash 验证rsync --version可用即可继续构建。注意版本需与 Git Bash 的运行环境通常为 MSYS2/MinGW兼容。错误二ln: failed to create symbolic link ../../desktop-client/public/kcab: Operation not permitted现象构建时创建符号链接失败报Operation not permitted。原因构建流程需要在desktop-client/public下创建符号链接目标名为kcab。在 Windows 上创建符号链接需要开发者模式或管理员权限普通权限的 shell 会被系统拒绝。解决官方文档给出的明确做法是——以管理员身份运行 Git Bash。如果已经以管理员身份运行仍失败请检查开发者模式是否已启用对应上文准备步骤 2该模式允许非提升进程创建符号链接。两步都满足后重试即可。更多排查方向围绕 Windows 构建仓库的 troubleshooting.md 还提供了几条与本主题直接相关的建议可一并参考构建产物残留删除packages/*/dist、packages/*/lib-dist、packages/*/build后重新yarn install版本校验node --version需 ≥ 22yarn --version需匹配 ^4.9.1原生模块失败Windows 下确认已安装 Python 与 Visual Studio Build Tools必要时执行yarn rebuild-electronElectron 场景或yarn workspace actual-app/core rebuildNode 场景。小结在 Windows 上构建 Actual 的关键可以归纳为一句话所有构建命令一律在管理员身份的 Git Bash 中执行。在此基础上依次完成环境准备、yarn install、yarn start:browser浏览器版或yarn start 按需yarn rebuild-electron桌面版并针对rsync缺失与符号链接权限两个高频问题提前做好准备即可获得与 Linux/macOS 一致的开发体验。进一步的环境搭建细节可参考 development-setup.md完整排查清单见 troubleshooting.md。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考