Actual Budget开发环境搭建与贡献指南-优快云博客

Actual Budget开发环境搭建与贡献指南

【免费下载链接】actual A local-first personal finance app 项目地址: https://gitcode.com/GitHub_Trending/ac/actual

本文详细介绍了Actual Budget项目的开发环境搭建流程、代码规范与质量保障工具链配置，以及贡献流程与社区协作最佳实践。内容涵盖项目依赖管理与Yarn Workspaces配置、开发环境快速搭建与调试技巧、ESLint和Prettier等代码规范工具的使用，以及GitHub工作流和代码审查流程等社区协作规范。

项目依赖管理与Yarn Workspaces配置

Actual Budget作为一个大型的本地优先个人财务系统，采用了现代化的Monorepo架构和Yarn Workspaces来管理复杂的项目依赖关系。这种架构设计使得多个包能够高效协同工作，同时保持清晰的依赖边界和版本管理。

Yarn Workspaces核心配置

Actual Budget使用Yarn 4.x作为包管理器，通过.yarnrc.yml文件进行全局配置：

compressionLevel: mixed
enableGlobalCache: false
enableTransparentWorkspaces: false
nodeLinker: node-modules
yarnPath: .yarn/releases/yarn-4.9.1.cjs

关键配置说明：

nodeLinker: 设置为node-modules，使用传统的node_modules目录结构
yarnPath: 指定使用项目内嵌的Yarn 4.9.1版本，确保版本一致性
enableTransparentWorkspaces: 禁用透明工作区，提供更明确的依赖管理

工作区包结构

项目采用标准的Monorepo结构，在根目录package.json中定义工作区配置：

{
  "workspaces": {
    "packages": [
      "packages/*"
    ]
  }
}

这表示所有在packages/目录下的子目录都被视为独立的工作区包。当前项目包含以下主要工作区：

包名称	版本	主要功能
`@actual-app/api`	25.8.0	核心API服务
`@actual-app/components`	0.0.1	UI组件库
`@actual-app/crdt`	2.1.0	CRDT同步引擎
`@actual-app/sync-server`	-	同步服务器
`@actual-app/web`	-	Web客户端
`loot-core`	0.0.2	核心业务逻辑
`desktop-electron`	-	桌面客户端

依赖管理策略

1. 工作区依赖引用

项目内部包之间的依赖使用workspace:协议进行引用，确保开发时使用本地源码：

{
  "dependencies": {
    "@actual-app/crdt": "workspace:^",
    "@actual-app/web": "workspace:*"
  }
}

workspace:^: 表示兼容版本的工作区依赖
workspace:*: 表示任意版本的工作区依赖

2. 外部依赖管理

外部依赖通过严格的版本锁定确保一致性。yarn.lock文件包含所有依赖的精确版本信息，确保在不同环境下的安装结果一致。

mermaid

脚本命令体系

根目录的package.json定义了丰富的脚本命令，充分利用Yarn Workspaces的特性：

# 运行特定工作区的命令
yarn workspace @actual-app/sync-server start

# 在所有工作区并行运行测试
yarn workspaces foreach --all --parallel --verbose run test

# 构建特定工作区
yarn workspace @actual-app/api build

# 生产环境安装（仅安装指定工作区）
yarn workspaces focus @actual-app/sync-server --production

依赖解析流程

当运行yarn install时，Yarn Workspaces会执行以下解析流程：

mermaid

版本冲突解决策略

项目采用多种策略来处理潜在的版本冲突：

resolutions字段: 强制统一特定包的版本

{
  "resolutions": {
    "rollup": "4.40.1",
    "socks": ">=2.8.3"
  }
}

补丁机制: 使用Yarn的patch功能修改第三方依赖

.yarn/patches/adm-zip-npm-0.5.16-4556fea098.patch

Peer Dependencies: 组件库使用peerDependencies避免重复安装

{
  "peerDependencies": {
    "react": ">=18.2",
    "react-dom": ">=18.2"
  }
}

开发环境优化

为了提升开发体验，项目配置了以下优化：

开发依赖共享: 常见的开发工具（TypeScript、Vitest、ESLint等）在根目录统一管理
构建工具链: 使用Vite作为统一的构建工具，支持热重载和快速构建
类型检查: 通过yarn typecheck命令进行全项目类型检查
代码质量: 集成Prettier和ESLint确保代码风格一致

生产部署策略

对于生产环境，项目支持多种部署方式：

# 构建浏览器版本
yarn build:browser

# 构建桌面应用
yarn build:desktop

# 构建服务器
yarn build:server

# 生产环境最小化安装
yarn install:server

这种依赖管理架构使得Actual Budget能够：

保持多个包之间的版本一致性
支持并行开发和测试
优化构建和部署流程
确保开发和生产环境的一致性
便于新贡献者快速上手项目结构

开发环境快速搭建与调试技巧

Actual Budget 作为一个现代化的本地优先个人理财工具，采用了基于 Node.js 的多包架构设计。对于开发者而言，快速搭建开发环境并掌握高效的调试技巧至关重要。本文将深入介绍 Actual Budget 的开发环境配置、构建系统、热重载机制以及实用的调试方法。

环境要求与初始化配置

Actual Budget 要求 Node.js 20+ 和 Yarn 4.9.1+ 版本。项目采用 Yarn Workspaces 管理多包依赖，确保所有包都能正确构建和链接。

# 克隆项目
git clone https://gitcode.com/GitHub_Trending/ac/actual.git
cd actual

# 安装依赖
yarn install

# 验证环境
node --version  # 确保 >= 20
yarn --version  # 确保 >= 4.9.1

项目结构采用多包架构，核心包包括：

包名称	功能描述	构建命令
loot-core	核心业务逻辑	`build:node`, `build:browser`
desktop-client	桌面客户端UI	`start:browser`, `build`
desktop-electron	Electron封装	`watch`, `build`
sync-server	同步服务器	`build`, `start`

Vite 驱动的开发服务器配置

Actual Budget 使用 Vite 作为构建工具，提供了高效的开发服务器和热重载功能。桌面客户端配置了专门的 Vite 插件来处理跨包依赖和文件监听。

// packages/desktop-client/vite.config.mts 关键配置
const addWatchers = (): Plugin => ({
  name: 'add-watchers',
  configureServer(server) {
    server.watcher
      .add([
        path.resolve('../loot-core/lib-dist/electron/*.js'),
        path.resolve('../loot-core/lib-dist/browser/*.js'),
      ])
      .on('all', function () {
        // 通知所有客户端静态文件变更
        for (const wsc of server.ws.clients) {
          wsc.send(JSON.stringify({ type: 'static-changed' }));
        }
      });
  },
});

开发服务器支持环境变量配置：

# 启动开发服务器（浏览器模式）
BROWSER_OPEN=localhost:5173 yarn start:browser

# 启动开发服务器（桌面模式）
yarn start:desktop

多环境构建与调试技巧

1. 浏览器环境开发

# 并行启动核心包和客户端
yarn start:browser

# 或分别启动
yarn workspace loot-core watch:browser  # 核心包监听
yarn workspace @actual-app/web start:browser  # 客户端开发服务器

流程图展示了浏览器环境的构建流程：

mermaid

2. Electron 桌面环境开发

# 完整的桌面开发环境
yarn start:desktop

# 分解步骤
yarn rebuild-electron  # 重建 Electron 原生模块
yarn workspace loot-core build:browser  # 构建核心包
yarn workspace loot-core watch:node  # 监听核心包变更
yarn workspace @actual-app/web watch  # 监听客户端变更
yarn workspace desktop-electron watch  # 启动 Electron

3. 调试配置与技巧

Chrome DevTools 调试：

// 在代码中添加调试断点
console.log('调试信息:', variable);
debugger;  // 自动暂停

// 使用条件断点
if (condition) {
  debugger;
}

VSCode 调试配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Electron Main",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/packages/desktop-electron/index.ts",
      "outFiles": ["${workspaceFolder}/packages/desktop-electron/build/**/*.js"]
    }
  ]
}

热重载与实时反馈机制

Actual Budget 实现了精细化的文件监听和热重载策略：

mermaid

关键监听路径包括：

../loot-core/lib-dist/electron/*.js - Electron 构建输出
../loot-core/lib-dist/browser/*.js - 浏览器构建输出
源代码目录的所有 TypeScript 和 JavaScript 文件

性能优化与构建调优

构建产物分析

# 生成构建分析报告
yarn workspace @actual-app/web build --mode production

Vite 配置中的可视化插件会生成详细的包分析数据，帮助识别性能瓶颈：

// 构建分析配置
visualizer({ 
  template: 'raw-data',
  filename: 'build/stats.html'
})

环境特定优化

# 开发环境构建（包含源码映射）
NODE_ENV=development yarn build:browser

# 生产环境构建（优化压缩）
NODE_ENV=production yarn build:browser

# 桌面特定构建
yarn build:desktop

常见问题排查指南

依赖问题：

# 清理并重新安装
rm -rf node_modules yarn.lock
yarn install

# 重建原生模块
yarn rebuild-electron
yarn workspace loot-core rebuild

端口冲突：

# 指定不同端口
PORT=3000 yarn start:browser

内存不足：

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" yarn start

通过掌握这些开发环境配置和调试技巧，开发者可以高效地进行 Actual Budget 的功能开发和问题排查。项目的模块化架构和现代化的构建工具链为快速迭代提供了坚实基础。

代码规范与质量保障工具链配置

Actual Budget 项目采用了一套完整的代码规范和质量保障工具链，确保代码库的一致性和高质量。这套工具链涵盖了代码格式化、静态分析、类型检查、测试覆盖等多个方面，为开发者提供了强大的质量保障机制。

ESLint 配置详解

项目使用 ESLint 作为主要的静态代码分析工具，配置采用了最新的扁平化配置格式（eslint.config.mjs）。配置包含了多个插件和规则集：

// eslint.config.mjs 核心配置结构
export default pluginTypescript.config(
  {
    ignores: [/* 忽略文件列表 */],
  },
  {
    files: ['packages/sync-server/**/*.spec.{js,jsx}'],
    languageOptions: { globals: { vi: true, describe: true, expect: true } }
  },
  {
    linterOptions: { reportUnusedDisableDirectives: true },
    languageOptions: { globals: { ...globals.browser, ...globals.commonjs, ...globals.node } }
  },
  pluginReact.configs.flat.recommended,
  pluginTypescript.configs.recommended,
  pluginImport.flatConfigs.recommended,
  {
    plugins: {
      actual: pluginActual,
      'react-hooks': pluginReactHooks,
      'jsx-a11y': pluginJSXA11y,
      'typescript-paths': pluginTypescriptPaths,
    },
    rules: {
      'actual/no-untranslated-strings': 'error',
      'actual/prefer-trans-over-t': 'error',
    }
  }
);

自定义 ESLint 规则

项目开发了专门的 ESLint 插件 @actual-app/eslint-plugin-actual，包含以下自定义规则：

规则名称	级别	描述
`no-untranslated-strings`	error	禁止使用未翻译的字符串
`prefer-trans-over-t`	error	优先使用 trans() 函数而非 t()
`typography`	warn	排版相关规范检查
`prefer-if-statement`	warn	条件语句最佳实践

Prettier 代码格式化

项目使用 Prettier 进行统一的代码格式化，配置在 package.json 的 lint-staged 部分：

{
  "lint-staged": {
    "*.{js,mjs,jsx,ts,tsx,md,json,yml}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

TypeScript 严格类型检查

项目配置了 TypeScript 严格模式，通过 typescript-strict-plugin 提供额外的类型安全保证：

{
  "scripts": {
    "typecheck": "yarn tsc --incremental && tsc-strict"
  },
  "devDependencies": {
    "typescript-strict-plugin": "^2.4.4"
  }
}

测试工具链配置

项目采用 Vitest 作为测试框架，配置了多种测试环境：

mermaid

测试脚本配置：

{
  "scripts": {
    "test": "yarn workspaces foreach --all --parallel --verbose run test",
    "test:debug": "yarn workspaces foreach --all --verbose run test",
    "e2e": "yarn workspaces foreach --all --exclude desktop-electron --parallel --verbose run e2e",
    "e2e:desktop": "yarn build:desktop --skip-exe-build && yarn workspace desktop-electron e2e",
    "playwright": "yarn workspace @actual-app/web run playwright",
    "vrt": "yarn workspaces foreach --all --parallel --verbose run vrt",
    "vrt:docker": "./bin/run-vrt"
  }
}

Husky Git 钩子配置

项目使用 Husky 配置 Git 预提交钩子，确保代码提交前的质量检查：

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,mjs,jsx,ts,tsx,md,json,yml}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

多包工作区管理

项目采用 Yarn Workspaces 管理多个包，每个包都有独立的配置：

mindmap
  root(Actual Budget 工作区)
    (loot-core)
      :::core
      (核心业务逻辑)
      (数据库操作)
      (API 接口)
    (desktop-client)
      :::ui
      (桌面客户端UI)
      (React 组件)
      (状态管理)
    (desktop-electron)
      :::electron
      (Electron 封装)
      (原生功能)
      (窗口管理)
    (component-library)
      :::components
      (共享组件库)
      (设计系统)
      (样式规范)
    (api)
      :::api
      (

【免费下载链接】actual A local-first personal finance app 项目地址: https://gitcode.com/GitHub_Trending/ac/actual

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考