1. 项目概述一个纯粹、高效的订阅费用追踪器在数字订阅服务泛滥的今天我们每个人的钱包都在被各种“自动续费”悄悄掏空。从流媒体、云服务到各种软件会员账单分散在各个平台支付周期也各不相同想要清晰地知道自己每个月、每年到底为这些服务花了多少钱往往需要手动整理一堆邮件和账单既繁琐又容易遗漏。这正是我决定动手搭建Subs这个开源订阅追踪器的初衷。Subs 是一个为追求简洁和隐私的用户设计的订阅管理工具。它的核心目标非常明确让你在一个地方快速、直观地掌握自己所有的周期性支出并且完全掌控自己的数据。它不像那些需要你注册账号、将财务数据上传到第三方云端的服务Subs 的设计哲学是“数据主权归你”。你可以选择将数据完全保存在自己的浏览器本地或者部署在自己的服务器上用一个简单的 JSON 文件来存储。整个项目基于现代 Web 技术栈Remix React Tailwind CSS构建界面清爽响应迅速无论是桌面端还是手机端操作体验都相当流畅。如果你是一名开发者厌倦了臃肿的商业软件想拥有一个完全受自己控制的订阅管理工具或者你是一名普通用户对个人数据隐私有要求希望找一个轻量、开源、能自部署的方案那么 Subs 值得你花时间了解一下。接下来我将从设计思路、技术实现、部署实践到使用技巧为你完整拆解这个项目。2. 核心设计思路与技术选型解析2.1 为什么是“纯前端优先”与“数据本地化”在构思 Subs 时我首先问自己用户最核心的痛点是什么答案是对个人财务数据的隐私担忧和对工具简洁性的追求。很多在线记账或订阅管理工具功能强大但过于复杂且数据存储在服务商那里总让人有些不放心。因此Subs 的架构设计围绕两个核心原则展开隐私与数据主权用户的数据应该尽可能留在用户可控的范围内。这催生了 Subs 独特的双存储模式。默认情况下项目使用一个服务端 JSON 文件data/config.json来存储数据。这意味着当你自行部署后所有数据都保存在你自己的服务器硬盘上没有中间商。对于更极致的隐私需求只需一个环境变量USE_LOCAL_STORAGEtrue即可切换到浏览器本地存储LocalStorage数据完全不出你的设备。简洁与高效功能聚焦于订阅管理的核心流程——增删改查、金额汇总、下次付款日提醒。没有复杂的预算分类、投资关联等冗余功能。界面采用shadcn/ui组件库基于 Tailwind CSS确保了视觉的一致性和开发的效率同时保持了极佳的加载速度。设计心得在工具类产品中克制往往比堆砌功能更难也更重要。Subs 刻意避免了用户账号系统因为一旦引入账号就必然涉及密码、会话、数据库用户表等一系列复杂度。通过“本地存储”和“服务器文件存储”这两种简单模式我们用一个非常轻量的架构就解决了数据持久化和隐私的核心诉求。2.2 技术栈选型的背后考量Subs 的技术栈看起来是现代 React 生态的一个典型组合但每个选择都有其具体原因Remix React为什么选择 Remix 而不是 Next.js 或纯 ReactRemix 的核心优势在于其“服务端为中心”的模型和对 Web 基础标准的拥抱如form提交、action/loader函数。对于 Subs 这样一个交互以表单为主添加、编辑订阅、且需要服务端读写文件JSON 存储模式的应用Remix 的模式非常自然。它简化了数据加载和提交的逻辑让服务端渲染SSR和客户端交互无缝结合。当然项目提供的关键词包含 Next.js说明其核心的 React 现代 CSS 模式同样可以迁移但 Remix 在当前架构下是更原生的选择。Tailwind CSS shadcn/ui快速构建美观、一致 UI 的黄金组合。Tailwind 的实用性优先Utility-First理念让样式开发速度飞快。shadcn/ui则提供了一套可以直接复制粘贴、高度可定制的 React 组件源码它不是一个 NPM 包而是你项目代码的一部分这避免了版本依赖冲突也让你能完全控制组件每一个细节。这对于需要精细调整交互的订阅列表、表单对话框非常友好。Zustand状态管理。相比 Redux 的繁琐Zustand 的 API 极其简洁一个 Store 文件就能管理所有的订阅状态列表、增删改查操作、过滤排序状态。它的轻量性和与 React 的完美融合使得在客户端管理订阅数据流变得清晰而高效。Playwright端到端E2E测试。对于一个管理数据的工具测试的可靠性至关重要。Playwright 支持多浏览器Chromium, Firefox, WebKit能模拟真实用户从打开页面、添加订阅、编辑到删除的完整流程确保核心功能在任何更新后都不会被意外破坏。Biome一个新兴的、速度极快的 JavaScript 工具链集成了格式化Formatting、代码检查Linting等功能用来替代 ESLint 和 Prettier。选择 Biome 主要是为了追求极致的工具链速度和一体化体验保持代码风格的统一。这套技术栈的搭配在开发体验、性能、可维护性和最终用户体验之间取得了不错的平衡。3. 功能详解与核心实现逻辑3.1 订阅数据模型与核心状态管理一个订阅的核心信息有哪些Subs 定义了一个清晰的数据结构这体现在 Zustand Store 和 TypeScript 类型定义中。每个订阅项Subscription大致包含以下字段interface Subscription { id: string; // 唯一标识通常使用 crypto.randomUUID() 生成 name: string; // 服务名称如 “Netflix” price: number; // 价格 currency: string; // 货币代码如 “USD”, “EUR”, “CNY” cycle: daily | weekly | monthly | yearly; // 计费周期 cycleCount: number; // 周期倍数例如每3个月cycle: ‘monthly’, cycleCount: 3 startDate: string; // ISO 8601 格式的开始日期如 “2024-01-15” // ... 可能还有分类、备注等扩展字段 }所有的订阅项被组织成一个数组存储在 Zustand 的subscriptionStore中。这个 Store 不仅保存数据还定义了所有操作数据的方法addSubscription,editSubscription,deleteSubscription,importFromJson,exportToJson等。状态流转的关键当用户在前端界面进行操作比如点击“保存”按钮时会调用 Store 中的对应方法。该方法会先更新内存中的状态保证UI立即响应然后根据当前配置的存储模式USE_LOCAL_STORAGE调用不同的持久化函数本地存储模式直接调用localStorage.setItem。服务端文件存储模式向一个特定的 Remixaction函数发起fetch请求由服务端将新数据写入data/config.json文件。这种设计将业务逻辑状态管理与持久化细节存储层解耦使得代码清晰且未来若要增加新的存储后端例如连接数据库也会相对容易。3.2 智能日期计算与多币种汇总这是 Subs 的两个核心实用功能。1. 下次付款日计算逻辑位于app/utils/nextPaymentDate.ts。计算原理并不复杂但需要考虑边界情况。核心思路是基于startDate和cycle计算出下一个大于或等于今天的日期。每月订阅从开始日期的“日”部分开始每月递增。需要处理月末特殊情况如1月31日之后的下次付款如果当月没有31日则退回到当月最后一天。每年订阅同理按年递增月份和日期。每周/每日订阅基于开始日期按周或日进行周期累加。实操要点在实现时强烈建议使用像date-fns或Day.js这样的日期库来处理日期加减和格式化避免原生Date对象时区和不直观的 API 带来的坑。Subs 的源码中应该包含了稳健的日期计算逻辑。2. 多币种汇总用户可能有美元、欧元、人民币等多种货币的订阅。直接相加是没有意义的。Subs 需要实现货币转换。数据来源需要一个可靠的汇率 API如 Open Exchange Rates, Fixer 等注意这些是第三方服务Subs 的演示或开源版本可能需要用户自行配置API密钥或使用免费额度。实现方式在服务端Remixloader或客户端初始化时获取一次基础汇率例如以 USD 为基准。前端展示时将所有非基准货币的订阅价格通过汇率换算成基准货币后加总得到总计。同时也可以在界面上展示各货币的原始小计。缓存策略汇率不需要实时更新可以每天或每小时从服务端获取一次并缓存以减少 API 调用次数和提升页面加载速度。3.3 响应式UI与键盘快捷键优化体验Subs 的界面布局充分利用了 Tailwind CSS 的响应式工具类。在桌面端列表可以更宽显示更多列信息如下次付款日、周期在移动端列表会垂直堆叠或者通过卡片形式展示关键信息确保触控操作方便。键盘快捷键是提升效率的利器。Subs 通过useEffect监听全局的keydown事件来实现n打开新建订阅表单。/将焦点跳到搜索框这是很多现代Web应用如Gmail、Notion的惯例。Ctrl/Cmd e/i导出/导入 JSON 数据。?打开快捷键帮助面板。Escape关闭任何打开的弹窗或下拉菜单。实现时需要注意当焦点在输入框等表单元素内时应禁用部分全局快捷键如/以免冲突。这可以通过检查event.target的标签名来实现。4. 从零开始部署与深度使用指南4.1 本地开发环境搭建假设你是一名开发者想在自己的机器上运行或贡献代码步骤如下环境准备确保系统已安装 Node.js 20 或更高版本。推荐使用nvm(Node Version Manager) 来管理多版本 Node.js。包管理器可以选择 npmNode 自带或速度更快的 Bun。获取代码git clone https://github.com/ajnart/subs.git cd subs安装依赖# 使用 npm npm install # 或使用 Bun bun install启动开发服务器npm run dev # 或 bun run dev访问http://localhost:3000你应该能看到 Subs 的界面。默认情况下数据会保存在项目根目录的data/config.json文件中如果该文件不存在首次添加订阅时会自动创建。4.2 生产环境部署方案Docker 推荐对于想长期自托管使用的用户Docker 是最简单、最一致的方式。方案一直接使用 Docker Run这是最快捷的尝鲜方式。以下命令会从 GitHub Container Registry 拉取官方镜像并将容器内的 7574 端口映射到宿主机的 7574 端口同时将宿主机的./data目录挂载到容器内用于持久化存储 JSON 数据文件。docker run -p 7574:7574 -v $(pwd)/data:/app/data --name subs --rm ghcr.io/ajnart/subs-p 7574:7574: 端口映射。-v $(pwd)/data:/app/data: 数据卷挂载这是关键确保你的订阅数据在容器重启后不会丢失。--name subs: 给容器起个名字。--rm: 容器停止后自动删除容器数据在挂载的卷里所以安全。ghcr.io/ajnart/subs: 官方镜像地址。方案二使用 Docker Compose推荐用于长期运行创建一份docker-compose.yml文件内容如下version: 3.8 services: subs: image: ghcr.io/ajnart/subs:latest container_name: subs ports: - 7574:7574 # 你可以改成其他端口如 “8080:7574” restart: unless-stopped # 容器意外退出时自动重启 volumes: - ./data:/app/data # 持久化数据目录 # 环境变量配置可选 # environment: # - USE_LOCAL_STORAGEfalse # 默认即为 false使用服务端文件存储 # - PORT7574 # 容器内部端口一般无需修改然后在同一个目录下执行# 启动服务后台运行 docker compose up -d # 查看日志 docker compose logs -f subs # 停止服务 docker compose down使用 Docker Compose 的优势是配置即代码易于版本管理和迁移。restart: unless-stopped能保证服务在服务器重启后自动运行。部署注意事项数据备份定期备份./data目录下的config.json文件。这是你所有订阅数据的命脉。安全考虑Subs 本身不包含用户认证。如果你将其部署在公网例如云服务器任何人都能访问并修改你的订阅数据。切勿在公网开放不设防的 Subs 服务解决方案是使用反向代理添加认证在 Subs 前面部署 Nginx 或 Caddy配置 HTTP 基本认证Basic Auth或集成 OAuth。仅在内网使用在家庭局域网或 VPN 后访问这是最安全的方式。汇率 API如果你需要多币种汇总功能且项目默认没有内置免费汇率源你需要自行申请一个汇率 API 的密钥并通过环境变量或配置文件注入到项目中。具体方式需参考项目源码的配置部分。4.3 进阶使用技巧与数据迁移1. 本地存储与服务端存储的切换如果你一开始在本地浏览器中使用USE_LOCAL_STORAGEtrue后来想迁移到自部署的服务端可以这样做在浏览器中使用 Subs 的导出Export功能下载一个subscriptions.json文件。将部署好的服务端 Subs 运行起来。在服务端 Subs 界面使用导入Import功能上传刚才下载的 JSON 文件。 这样就完成了数据迁移。反之亦然。2. 键盘快捷键的肌肉记忆养成使用快捷键的习惯能极大提升操作效率。尤其是n新建和/搜索是使用频率最高的两个操作。你可以把?快捷键的帮助面板当作一个随时可查的备忘单。3. JSON 数据的手动编辑对于高级用户你可以直接编辑data/config.json文件来批量修改订阅。文件结构是明文的 JSON可读性很强。但在编辑前务必停止 Subs 服务或确保没有正在写入的操作并做好备份以免损坏数据格式导致应用无法读取。5. 常见问题排查与开发者贡献指南5.1 使用与部署问题速查表问题现象可能原因解决方案访问http://localhost:3000空白或错误依赖未安装或端口被占用1. 确保已运行npm install。2. 检查端口 3000 是否被其他程序占用可尝试npm run dev -- --port 3001更换端口。Docker 容器启动后无法访问端口映射错误或防火墙限制1. 检查docker run -p或 Compose 文件中的端口映射主机端口:容器端口。2. 确保主机防火墙开放了对应端口如 7574。添加订阅后刷新页面数据丢失存储模式或权限问题1. 在 Docker 部署中检查-v挂载的目录是否有写权限./data:/app/data。2. 确认USE_LOCAL_STORAGE环境变量设置是否符合预期。服务端模式下查看data/目录下是否生成了config.json文件。货币汇总显示为 0 或 NaN汇率 API 未配置或失败1. 检查浏览器控制台Console是否有获取汇率接口的网络错误。2. 查看项目文档确认是否需要配置汇率 API 密钥。生产环境构建失败 (npm run build)TypeScript 类型错误或依赖问题1. 先运行npm run typecheck和npm run lint查看具体错误。2. 尝试删除node_modules和package-lock.json重新npm install。Playwright 测试失败浏览器驱动未安装或环境问题1. 首次运行前执行npx playwright install安装测试浏览器。2. 在无头环境中运行测试可能需要安装额外的系统依赖请参考 Playwright 官方文档。5.2 为开源项目贡献代码如果你在使用中发现 Bug或者有很棒的新功能想法非常欢迎向 Subs 项目贡献代码。流程是标准的 GitHub 协作模式Fork 仓库在 GitHub 上点击项目页面的 “Fork” 按钮创建你自己的副本。克隆与分支git clone https://github.com/你的用户名/subs.git cd subs git checkout -b feat/your-feature-name # 创建功能分支开发与测试进行代码修改。务必确保新功能有相应的测试如果是功能代码添加 Playwright E2E 测试如果是工具函数添加单元测试。在提交前运行项目提供的检查脚本npm run typecheck # 确保 TypeScript 类型正确 npm run lint # 确保代码风格符合 Biome 规范 npm run test # 确保所有测试通过提交与推送git add . git commit -m feat: 添加了XXX功能 # 使用清晰的提交信息 git push origin feat/your-feature-name发起 Pull Request (PR)回到 GitHub 上你的仓库页面通常会有一个提示让你为你刚推送的分支创建 PR。点击后选择向原仓库ajnart/subs的main分支发起合并请求。在 PR 描述中详细说明你的修改内容、动机以及测试情况。给贡献者的建议在开始开发新功能前最好先在项目的 Issue 列表里查看是否有相关讨论或者新建一个 Issue 描述你的想法与维护者我达成共识后再动手这样可以避免重复劳动或方向偏差。