Actual 的 Preview 与 Nightly 构建体系：PR 预览、每日构建与 Docker nightly 镜像使用指南

Actual 的 Preview 与 Nightly 构建体系：PR 预览、每日构建与 Docker nightly 镜像使用指南

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

Actual 是一款 local-first 的个人财务管理应用。为了让贡献者与尝鲜用户在不克隆分支、不编译源码的前提下体验最新改动，仓库围绕 Netlify 与 GitHub Actions 搭建了一套完整的"预览构建（Preview Builds）+ 每日构建（Nightly Builds）"体系：每个 Pull Request 自动部署三类在线预览，每天午夜自动产出桌面端安装包与 Docker 镜像。本文以 packages/docs/docs/contributing/preview-builds.md 为主线，结合仓库中的 CI 工作流与前端源码，完整讲解每类预览的 URL 规则、使用步骤、数据来源与安全注意事项，读完即可立刻上手验证 PR、体验每日新功能，并为自己的数据安全做出正确选择。

一、PR 预览构建：每次 Pull Request 的自动部署

仓库为每一个 Pull Request 自动部署预览到 Netlify，无需克隆分支即可体验分支上的改动。要使用预览，先浏览仓库的开放 Pull Requests 列表找到目标 PR，记下其编号（{pr-number}），然后替换到下面的 URL 模板中。

每个 PR 会部署三种预览：

除了手动拼接 URL，Netlify bot 还会自动在每个 PR 的评论中发布这组精确的预览地址，打开 PR 页面即可直接点击进入，无需自己替换编号。

从 CI 配置看，正式发布版本（tag 推送）同样走 Netlify 部署：.github/workflows/netlify-release.yml 中通过yarn build:browser构建前端，再以netlify deploy --dir packages/desktop-client/build发布到生产环境，PR 预览正是这套 Netlify 部署机制的预览化变体。

二、Demo 预览与 in-app 通知流（news feed）机制

Demo 预览的一个重要特性是：它的应用内通知流（news feed）来自该 PR 分支自身构建时提交的packages/desktop-client/src/data/news.json。这意味着，如果某个 PR 同时新增了一篇博客文章（发布公告），只要 CI 重新生成了 feed，这篇博文就会出现在该 PR 的 Demo 预览应用中，方便在真实界面里验证发布内容。

这个机制在前端源码中有完整的实现依据。packages/desktop-client/src/news/fetchNewsFeed.ts 定义了新闻源地址的三级优先级：

1. 显式覆盖：REACT_APP_NEWS_FEED_URL环境变量（例如在packages/desktop-client目录下的本地.env文件中设置），优先级最高；
2. Netlify PR 预览：当检测到REACT_APP_REVIEW_ID环境变量（Netlify 为 PR 部署注入）时，通过 Vite 的?url静态资源语法加载本构建打包的news.json，即精确对应 PR 分支上提交的文件——这样 fork 分支（其分支不在上游仓库中）也能正常加载自己的 feed；
3. 默认兜底：直接指向上游master分支上提交的packages/desktop-client/src/data/news.json（REPO_NEWS_FEED_URL常量）。

拿到 JSON 后，fetchNewsFeed.ts 还会做运行时结构校验（isNewsFeed/isNewsEntry），检查schemaVersion、entries数组以及每条记录的id、type、title、date、url、body等字段，防止不可信的远程内容破坏应用。对应的测试 packages/desktop-client/src/news/fetchNewsFeed.test.ts 覆盖了环境变量为空、显式指向本地 feed URL 等场景。

本地开发时如何指向其他 feed

官方文档给出的做法是：在packages/desktop-client目录下创建.env文件，设置REACT_APP_NEWS_FEED_URL指向任意 feed 地址：

# 位于 packages/desktop-client/.env REACT_APP_NEWS_FEED_URL=http://localhost:3000/news.json

该变量的作用域由源码中的import.meta.env.REACT_APP_NEWS_FEED_URL（Vite 环境变量机制）读取，因此必须在packages/desktop-client包内构建时生效。设置为空字符串或未设置时，则回落到上面第二、第三优先级逻辑。

三、预览构建的重要注意事项：没有同步服务器

:::info 关键提醒预览构建不包含同步服务器（sync server）。首次进入 Demo 预览时，应用会询问"Where's the server?"（服务器在哪），此时请选择"Don't use a server"（不使用服务器）；或者你也可以连接自己自建的同步服务器。 :::

需要特别强调的是安全警告：预览构建相比正式版出现 Bug 的概率高得多，其中某些 Bug可能损坏你的预算数据。如果坚持要在预览构建上使用服务器，建议专门为预览运行一个独立的本地服务器，与存放真实数据的服务器隔离，绝不要用生产数据去连接预览构建。

四、Nightly 每日构建：官方月度发布前的试验场

Nightly 构建充当即将进入官方月度发布的新功能的测试场地。它比 PR 预览更新更频繁、更接近主干，适合想抢先体验最新特性的用户；但也要清醒地认识到：新功能会被频繁地添加和移除，因此Nightly 构建并不总是稳定。官方文档对 Nightly 给出了与预览构建相同的服务器提示与数据安全警告（没有同步服务器 / 谨慎连接自建服务器 / 建议独立本地服务器）。

Nightly 构建分三条渠道发布：Web 版、桌面版、Docker 镜像。

4.1 Nightly Web 构建（在线试用）

想直接体验每日构建的 Web 应用，访问https://nightly.actualbudget.org/即可，无需安装任何东西。它同样没有同步服务器，进入时选择 "Don't use a server"，或连接自己的自建服务器。

4.2 Nightly 桌面端构建（下载安装包）

桌面应用（安装与使用说明见 packages/docs/docs/install/desktop-app.md）也每天构建一次。安装包以GitHub Actions 工作流产物（artifacts）的形式发布。该流程对应 .github/workflows/publish-nightly-electron.yml：工作流通过schedule: cron '0 0 * * *'每天午夜触发，在 Ubuntu、Windows、macOS 三个平台矩阵上并行构建，产出覆盖多平台多架构的安装包。

下载最新 Nightly 桌面构建的完整步骤：

1. 登录 GitHub：GitHub 仅允许已登录用户下载 workflow artifacts，免费账号即可；
2. 打开 Nightly 桌面构建运行列表：进入Publish nightly desktop app工作流页面，筛选is:success显示成功记录，点击列表**最顶部（最新）**的一次运行；
3. 滚动到页面底部的 Artifacts 区域；
4. 下载匹配你操作系统与处理器架构的产物。从 publish-nightly-electron.yml 可以看到按命名区分的产物清单：
   • Linux：Actual-linux-x86_64.AppImage（x64）、Actual-linux-arm64.AppImage（arm64）
   • Windows：Actual-windows-ia32.exe（32 位）、Actual-windows-x64.exe（64 位）、Actual-windows-arm64.exe（arm64），另附 Windows Store 的.appx包
   • macOS：Actual-mac-x64.dmg（Intel）、Actual-mac-arm64.dmg（Apple Silicon）
5. 解压并安装：产物以.zip压缩包下载，解压后得到安装程序，像安装正式版桌面应用一样安装即可。

（补充：仓库还维护了 .github/workflows/electron-pr.yml，对每个 PR 同样产出各平台 Electron 安装包产物，供贡献者在本地系统上验证分支改动。）

4.3 Nightly Docker 镜像

如果你用 Docker 自建同步服务器，Nightly 镜像同样可用。详见 packages/docs/docs/install/docker.md#nightly-tag 中的说明。核心要点如下：

• 镜像仓库：官方镜像发布到 Docker Hub（actualbudget/actual-server）与 GitHub Container Registry（ghcr.io/actualbudget/actual），两个来源功能一致，任选其一；
• nightly标签：每次向master分支推送提交都会更新。提供nightly与nightly-alpine（基于 Alpine Linux，体积小，适合低功耗设备）两个标签；作为对比，latest标签指向最近一次官方正式发布，是大多数用户的推荐选择。

从构建源头 .github/workflows/docker-nightly.yml 可以确认：该工作流在每次master推送（或手动触发workflow_dispatch）时构建镜像，使用packages/sync-server/docker/ubuntu.Dockerfile与packages/sync-server/docker/alpine.Dockerfile两个基础镜像变体，并同时打出nightly、edge（为向后兼容保留）与sha三种标签，推送至 Docker Hub 与 GHCR，构建目标覆盖linux/amd64、linux/arm64（Alpine 变体还额外支持linux/arm/v7、linux/arm/v6）。构建完成后会先启动容器跑一次健康检查（docker run ... actualbudget/actual-server-testing，依据packages/sync-server/docker-compose.yml中的 healthcheck 命令验证）再推送，确保 nightly 镜像可正常启动。

用 Docker 命令运行 nightly 镜像的示例（将数据目录替换为你主机上的路径）：

docker run --pull=always --restart=unless-stopped -d -p 5006:5006 \ -v YOUR/PATH/TO/DATA:/data --name my_actual_budget \ actualbudget/actual-server:nightly

同样可以用docker compose管理，更新时执行docker compose pull && docker compose up -d即可。

五、使用总结与安全准则

无论使用哪一条预览/夜间渠道，都请牢记三点：

1. 预览与 Nightly 构建没有自带同步服务器，首次进入选择 "Don't use a server"，或连接你自己的自建服务器；
2. 这些构建比正式版更容易出现损坏预算数据的 Bug，务必在使用前为预算文件保留备份；
3. 若必须连接服务器，为预览/夜间构建单独运行一个本地服务器，与真实数据环境隔离。

上述全部机制与源码证据，均可在仓库中进一步追踪：预览部署相关的 CI 见 .github/workflows/netlify-release.yml 与 .github/workflows/electron-pr.yml，Nightly 桌面构建见 .github/workflows/publish-nightly-electron.yml，Nightly 镜像见 .github/workflows/docker-nightly.yml，通知流解析逻辑见 packages/desktop-client/src/news/fetchNewsFeed.ts 及其测试 packages/desktop-client/src/news/fetchNewsFeed.test.ts。

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