几个月前，一位开发者被同一个问题反复折磨：“我上次看到哪一集了？”为了回答这个简单的问题，他常常要在好几个应用之间来回翻找。一部剧刚看上头，工作一忙搁置几周，再回来就彻底记不清进度。有时对着剧集列表反复翻看，有时干脆把已经看过的内容又重刷了一遍。被这种体验折腾到受不了之后，他决定自己动手，做一个专属于自己的追踪工具。
工具的思路很直接：搜索想看的剧，加入列表，每看完一集就点一下按钮。不过，在这份简单的体验背后，藏着几个值得琢磨的设计决策。观看进度怎么存储？剧集信息是每次都向外部 API 请求，还是一劳永逸地缓存到 MongoDB 里？怎样同时更新进度和状态，又不引发竞态条件？这篇教程正是围绕这些问题展开，基于 MongoDB、TanStack Start 和 TMDB 公开接口，带你从头构建一个全栈影视追踪应用。完整代码已经放在 GitHub 仓库里，可以直接拿来用。
跟着走完整个过程，你会重点掌握三件事：为追剧场景设计合理的数据模型；借助 MongoDB 聚合管道实现顺畅的进度更新和统计；再用 TanStack Start 的 server functions，在 React 全栈项目里轻松操作数据库。开始前，请确保本机安装了 Node.js 18 及以上版本，有 MongoDB Atlas 账号或本地 MongoDB 实例，以及一个免费 TMDB 账号用来获取 API token。此外，对 React、TypeScript 和 TanStack Start 有基础了解即可。
项目搭建基于 TanStack Start 的 start-basic 模板。先用 gitpick 把基础文件夹提取出来，安装依赖，然后引入 MongoDB Node.js 驱动，四行命令就位：
npx gitpick TanStack/router/tree/main/examples/react/start-basic tanstack-start-mongodb-tvshow-tracker
cd tanstack-start-mongodb-tvshow-tracker
npm install
npm install mongodb
这样就在内置了 Zod 等常用依赖的骨架上，立起了项目雏形。后续教程还提供了初始化脚本，一条 curl 命令就能清理示例文件、更新根路由，同时建好整个教程所需的目录和占位文件，省去大量手动搭建的力气。
后文会逐步展开用户界面、服务端接口和数据库操作的具体实现，但核心逻辑一句话就足够清晰：用 MongoDB 负责数据持久化，用 TanStack Start 把前后端融为一体，用 TMDB 补齐影视信息，从此彻底告别靠记忆猜进度的日子。
热门跟贴