1. 项目概述一个为家庭协作烹饪而生的智能周度餐食规划系统如果你和我一样家里有5口人每天下班后还要面对“今晚吃什么”的灵魂拷问以及随之而来的混乱采购和厨房分工问题那你一定能理解一个高效、清晰的餐食规划系统有多重要。我尝试过各种App和纸质表格但它们要么太死板要么无法适应我们家独特的“分阶段协作”烹饪流程——通常是有人提前准备有人负责收尾。于是我决定自己动手用现代Web技术栈打造一个完全贴合我们家庭工作流的周度餐食规划系统也就是这个“Food of the Week”项目。这不仅仅是一个简单的食谱列表。它是一个完整的解决方案从每周的头脑风暴、食谱结构化编写到自动生成一个美观、可打印、带有交互式购物清单的网站再到厨房里分阶段执行的烹饪指引。它的核心是将混乱的餐食规划流程化、自动化让家庭烹饪从一项令人头疼的任务变成一项可以高效协作、甚至享受乐趣的日常活动。系统特别为“提前备餐”尤其是真空低温烹饪和“家庭分工”这两个场景做了深度优化通过清晰的“快速预览”和“三阶段指令”让每个家庭成员都知道自己该在什么时候做什么。整个系统基于Astro构建生成静态网站部署在GitHub Pages上完全免费且加载飞快。无论你是热爱烹饪的极客还是只想让家庭晚餐变得更有序的家长这个项目的设计思路和实现细节或许都能给你带来启发。2. 核心设计理念与工作流拆解2.1 为何选择“周度规划”与“分阶段协作”传统的餐食规划工具大多是为单人烹饪设计的它们假设一个人会完成从备菜到上桌的所有步骤。但在多人口家庭尤其是双职工家庭中这往往不现实。我们的核心需求是异步协作一个人通常是“副厨”Sous Chef可以在下午或傍晚早些时候开始准备工作而另一个人“主厨”Chef则在稍晚时候加入完成最后的烹饪和摆盘。基于此我设计了三个明确的阶段Already Prepped (已备好)指那些已经提前完成只需加热或简单组合的食材比如真空低温烹饪好并分装的肉类、预煮的蔬菜。Sous Chef (副厨)这是协作的关键。副厨在主厨回家前需要完成的准备工作清单包括切配、启动真空低温烹饪机、煮饭等。Chef Finishing (主厨收尾)主厨到家后负责需要较高烹饪技巧或即时操作的部分如煎制、调味、酱汁收浓、摆盘等。这种划分明确了责任边界避免了厨房里的指令混乱。系统通过颜色区分这三个阶段让任何人在查看食谱时都能一目了然。2.2 技术选型为何是 Astro Tailwind CSS在技术栈上我追求的是极致的性能、简单的部署和高度的可定制性。Astro这是项目的基石。Astro 的“岛屿架构”让我可以只在真正需要交互的地方比如购物清单的复选框加载JavaScript其余部分都是纯静态HTML这保证了页面的加载速度极快。对于餐食规划这种以内容阅读为主的场景首屏性能至关重要。同时Astro 支持使用.astro、.md、React/Vue 等多种组件灵活性很高我用它来解析 Markdown 食谱并渲染成漂亮的页面结构非常顺手。Tailwind CSS样式系统的核心。餐食规划网站需要清晰的信息层级和愉悦的视觉体验。Tailwind 的效用优先Utility-First理念让我能快速构建响应式界面并且通过一个集中的配置文件tailwind.config.mjs管理所有设计令牌颜色、间距、字体等。这对于实现后面会讲到的灵活的色彩系统至关重要。TypeScript用于编写解析器weekParser.ts和工具函数。食谱的 Markdown 结构需要被精确解析以提取“快速预览”等信息TypeScript 的静态类型检查能极大减少运行时错误让代码更健壮。GitHub Pages Actions实现自动化部署。每次我将规划好的周度食谱 Markdown 文件推送到 GitHub 仓库GitHub Actions 会自动触发构建npm run build并将生成的静态文件部署到 GitHub Pages。整个过程在2-3分钟内完成完全无需手动干预。这个技术组合在开发体验和最终产出之间取得了完美平衡开发时高效灵活产出的网站则快速、稳定且易于维护。2.3 项目结构与数据流内容如何变成网站理解项目结构是自定义它的前提。整个系统的数据流非常清晰用户编辑 Markdown (FOOD-OF-THE-WEEK.md) ↓ Astro 页面 (src/pages/index.astro) 加载该文件 ↓ 调用自定义解析器 (src/utils/weekParser.ts) ↓ 解析出1. 餐食列表 2. 快速预览数据 3. 购物清单 ↓ 将数据传递给 Astro 组件 (MealCard.astro, GroceryList.astro) ↓ 组件结合 Tailwind 样式和色彩配置进行渲染 ↓ 生成最终静态 HTML/CSS/JS ↓ 通过 GitHub Actions 部署到 GitHub Pages关键目录说明FOOD-OF-THE-WEEK.md这是唯一的真相之源。你每周只需编辑这个Markdown文件。所有内容——餐食名称、食材、三阶段指令——都写在这里。src/utils/weekParser.ts这是项目的“大脑”。它采用基于位置的解析策略而非依赖特定关键词。这意味着无论你的Markdown里写的是“### Ingredients”还是“### 材料”只要它出现在预期的标题层级和相对位置解析器就能正确抓取信息。这种设计使得食谱格式非常自由。src/components/MealCard.astro负责渲染单个餐食的所有信息包括解析出的三阶段指令并应用循环的色彩方案。public/print-config.json一个独立的配置文件用于控制打印页面的样式边距、字体等实现样式与功能的解耦。实操心得将内容与配置分离将核心内容食谱放在 Markdown 中将样式配置放在tailwind.config.mjs和print-config.json中这是一个非常关键的设计。它允许完全不懂代码的家人也能通过编辑简单的文本文件来更新每周食谱而我作为开发者可以独立调整网站的外观和打印格式两者互不干扰。3. 核心功能深度解析与实操要点3.1 “快速预览”系统餐食规划的“仪表盘”这是整个系统提升效率的灵魂功能。它的目标是在一秒钟内告诉副厨“这顿饭需要我投入多少精力关键的时间节点是什么”实现机制在FOOD-OF-THE-WEEK.md中每个餐食标题##下方紧接着使用#####(H5) 和######(H6) 来定义快速预览。H5行是“代号”概括工作类型和强度如SousVidePrep。H6行是“时间详情”列出具体行动和关键时间点如prep toast panko 5:30 rice。weekParser.ts会精确识别这种结构提取信息并在网站首页顶部生成一个可点击的“英雄摘要”栏同时也在每个餐食卡片上展示。代号详解与使用策略代号含义从副厨视角适用场景实操建议PrepHeat基础切配简单加热塔可、简单炒菜、组装型菜肴如卷饼副厨工作较轻主要是切菜和操作烤箱/炉灶加热预制品。SousVidePrep真空低温烹饪设置辅助备餐需要启动真空机烹饪蔬菜或肉类同时可能需准备其他配菜副厨需要管理真空低温烹饪的时间和温度这是核心任务。SousChefDish副厨负责完整烹饪流程烤盘菜、一锅煮意面、需要全程照看的炖菜副厨承担主要烹饪责任主厨可能只需最后调味或摆盘。强度修饰符 / 的使用表示额外步骤或多组件。例如SousVidePrep可能意味着除了启动真空机还需要制作面包糠或准备酱汁。表示高度复杂、多步骤的工作。例如SousVidePrep可能涉及自制面包真空烹饪两种食材准备复杂酱料。编写时间详情的黄金法则具体化写“5:30 rice”5:30启动电饭煲而不是“煮饭”。行动化写“toast panko”烤面包糠、“chop mirepoix”切蔬菜基底。精简通常只包含1-2个最关键的时间点或步骤。避免把整个食谱步骤都列上去。避免重复如果代号已是SousVidePrep时间详情里就无需再写“sous vide”直接写“4:00 mire poix”即可。注意事项解析器的容错性这个基于位置的解析器虽然灵活但也要求格式相对规整。确保H5和H6是紧挨着餐食主标题##的下一行。中间如果有空行或其他内容解析可能会失败。在weekParser.ts中我通过严格的标题层级检测和相邻行分析来保证准确性但用户在编辑时仍需保持格式一致。3.2 交互式购物清单状态持久化的实现购物清单是另一个高频交互点。它的核心需求是勾选状态需要在本周内持久保存即使刷新浏览器或改天打开也不能丢失。技术实现数据源清单条目同样从FOOD-OF-THE-WEEK.md中解析出来通常放在一个## Grocery List章节下使用Markdown的无序列表- [ ] 物品名表示。状态管理在GroceryList.astro组件中我为每个复选框绑定了一个change事件监听器。持久化存储当复选框状态变化时使用localStorage.setItem将整个清单的完成状态一个布尔值数组或对象保存到浏览器的本地存储中。存储的键名包含了当前周的标识符例如从日期衍生这样就实现了按周隔离的状态存储不会和上周的清单混淆。水合当页面加载时组件使用Astro.global或Astro.cookies获取周标识符然后用localStorage.getItem读取对应的状态并据此设置复选框的初始checked属性。// 简化示例逻辑 const weekKey grocery-list-${currentWeekId}; // 保存状态 function saveState(items) { const state items.map(item item.checked); localStorage.setItem(weekKey, JSON.stringify(state)); } // 加载状态 function loadState() { const saved localStorage.getItem(weekKey); return saved ? JSON.parse(saved) : null; }避坑技巧处理 localStorage 的同步问题在服务端渲染SSR或静态生成SSG环境下localStorage是不可用的因为它是一个浏览器API。在 Astro 中我通过将交互逻辑封装在客户端脚本script标签内或使用client:load指令来确保这部分代码只在浏览器中运行。同时初始状态的设置要小心避免服务端和客户端渲染不一致导致的水合错误。3.3 智能粘性头部与打印功能智能粘性头部StickyHeader.astro组件实现了两种状态。页面顶部时显示一个简约的厨师帽图标当用户向下滚动时头部扩展为完整的导航栏显示本周所有餐食的“快速预览”代号点击可快速跳转。这通过监听window.scroll事件并添加/移除CSS类来实现同时兼顾了移动端的触摸体验。打印功能打印不是简单的window.print()。我编写了printGenerator.ts它会读取public/print-config.json中的配置动态生成一个用于打印的隐藏iframe或新窗口。在这个打印视图中可以只打印购物清单隐藏食谱细节。打印完整的周度计划并控制是否在每个餐食间分页。应用完全独立的打印样式字体、边距、复选框样式。确保复选框的勾选状态也能被正确打印出来。配置打印你完全可以通过修改print-config.json来定制打印效果无需改动代码。例如将pageBreakBetweenMeals: true改为false餐食就不会分页打印。4. 色彩系统与深度自定义指南4.1 色彩系统架构单一数据源原则为了让颜色管理清晰且易于维护我确立了Tailwind CSS 配置为唯一数据源的原则。架构流程1. 定义 (tailwind.config.mjs) - 基础色板 (theme.extend.colors) - 指令循环色板 (theme.extend.instructionPalette) - 子区域覆盖 (theme.extend.instructionSubsections) 2. 引用与派生 (src/config/colors.ts) - 从Tailwind配置导入颜色 - 编写逻辑根据色板名称自动生成背景色、边框色、文字色变体 - 处理循环逻辑当指令区块多于色板颜色时自动从头开始循环 3. 应用 (组件) - 静态类名直接使用Tailwind工具类如 bg-salmon-100 - 动态样式通过导入的 colors.ts 函数获取计算后的颜色值用于内联样式或CSS变量这种设计的好处一致性全站颜色只在一个地方定义。可维护性改颜色只需修改配置文件全局生效。灵活性colors.ts中的逻辑允许进行动态计算如循环、派生变体而组件无需关心这些逻辑。4.2 实操如何自定义你的主题假设你觉得默认的 salmon鲑鱼粉、yellow黄、orange橙循环色板看腻了想换成一套莫兰迪色系。步骤1修改基础色与循环色板打开tailwind.config.mjs找到theme.extend部分。// tailwind.config.mjs export default { theme: { extend: { colors: { // 1. 你可以先更改一些基础色 primary: #4A5568, // 从深棕改为灰蓝 secondary: #68D391, // 从亮黄改为绿色 accent: #F687B3, // 从橙色改为粉色 bg: #F7FAFC, bg-alt: #EDF2F7, border: #E2E8F0, }, instructionPalette: [ // 2. 完全替换循环色板 { name: sage, color: #9CAF88 }, // 鼠尾草绿 { name: clay, color: #CC978E }, // 黏土粉 { name: stone, color: #A8B2B9 }, // 石灰石灰 { name: mauve, color: #B8A1C9 }, // 淡紫色 (新增第四色) ], instructionSubsections: { info: { bg: bg-alt, border: secondary, heading: primary }, overrides: { // 3. 你可以覆盖特定位置的颜色 // 例如强制让第一个指令区块使用新的 mauve 色系而不是循环开始的 sage 0: { scheme: mauve }, // 或者为第三个区块指定一个固定颜色不来自色板 2: { border: #F6AD55 }, // 使用一个琥珀色边框 }, }, }, }, }步骤2理解colors.ts的派生逻辑你不需要修改colors.ts因为它会自动读取新的instructionPalette。它的工作是根据你定义的color例如#9CAF88自动计算出对应的浅背景色sage-100和深标题色sage-800。这些计算后的颜色名会注册到Tailwind中所以你可以在组件里直接使用bg-sage-100这样的类。步骤3在组件中应用在MealCard.astro或相关组件中系统会调用colors.ts中的getInstructionColor(index)函数。这个函数会根据索引和你的配置返回对应区块应该使用的颜色方案名如sage。然后组件会用这个名称去拼接Tailwind类例如bg-${scheme}-100。重要提醒关于边框样式由于项目配置中设置了applyBaseStyles: falseTailwind 不会自动注入基础样式。这意味着当你使用边框类如border-l-4时必须同时指定边框样式例如border-l-4 border-solid。否则边框可能不会显示。这是一个常见的坑点。4.3 响应式设计与移动端优化餐食规划网站经常在手机上查看尤其是在超市购物时。因此全面的响应式设计是必须的。布局响应利用 Tailwind 的响应式前缀如md:flex-row。在移动端餐食卡片通常是垂直堆叠在平板或桌面端可能会并排显示“快速预览”和详细指令。字体与间距使用相对单位rem和 Tailwind 的尺寸工具类text-sm,p-4,space-y-4来确保在不同屏幕尺寸下的可读性和触摸友好性。交互优化购物清单的复选框和粘性头部的导航按钮都经过了加大触摸区域min-touch-target的处理。打印按钮在移动端可能会改变位置或样式以确保易用性。图片与图标使用srcset或 Astro 的 Image 组件优化图片确保快速加载。图标使用SVG格式保证清晰度。5. 开发、部署与维护实战5.1 本地开发环境搭建克隆仓库git clone https://github.com/sh-ui/food-of-the-week.git安装依赖确保你安装了 Node.js (推荐 LTS 版本)然后在项目根目录运行npm install。启动开发服务器运行npm run dev。Astro 的开发服务器支持热重载你对FOOD-OF-THE-WEEK.md或任何源代码的修改都会实时反映在浏览器中通常是http://localhost:4321。构建与预览运行npm run build进行生产构建然后用npm run preview预览构建结果检查是否有问题。5.2 自动化部署流水线部署完全由 GitHub Actions 自动化。核心文件是.github/workflows/deploy.yml。# 简化的工作流示例 name: Deploy to GitHub Pages on: push: branches: [ main ] # 推送到 main 分支时触发 jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 - run: npm ci # 使用干净的依赖安装 - run: npm run build # 执行构建 - uses: peaceiris/actions-gh-pagesv3 # 使用部署 Action with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist # Astro 默认的输出目录工作流程当你编辑完FOOD-OF-THE-WEEK.md并推送到 GitHub 后这个 Action 会自动检出代码。安装依赖。执行npm run build生成静态文件到dist目录。将dist目录的内容推送到仓库的gh-pages分支。GitHub Pages 服务会自动从gh-pages分支拉取内容并发布。整个过程通常只需2-3分钟之后你的家人就可以通过https://你的用户名.github.io/food-of-the-week访问到最新的餐食计划了。5.3 依赖管理与更新策略项目使用Dependabot来自动化管理依赖更新。配置在.github/dependabot.yml中我设置了每周检查 npm 生产依赖的更新每月检查 GitHub Actions 的更新。流程Dependabot 检测到新版本后会自动创建 Pull Request。我会审查这些PR特别是主要版本升级如 Astro 从 4.x 到 5.x在本地测试无误后合并。安全更新对于安全补丁Dependabot 会创建高优先级的 PR应尽快合并。维护心得保持依赖健康对于个人项目我建议将 Dependabot 的频率设置为每月一次而不是每周。这既能及时获得安全更新又不会因为过于频繁的次要版本更新而产生太多“噪音”。在合并主要版本更新前务必仔细阅读官方迁移指南并在本地充分测试。项目中的MIGRATION.md文件就是用来记录这些升级计划和注意事项的。6. 常见问题排查与实战技巧在实际使用和开发过程中你可能会遇到以下问题。这里是我总结的排查清单和解决方案。6.1 内容解析相关问题问题现象可能原因解决方案“快速预览”没有显示在首页英雄栏H5/H6标题没有紧跟在餐食主标题##之后检查FOOD-OF-THE-WEEK.md文件格式确保#####和######行是##标题后的紧接着的两行。中间不要有空行或其他内容。购物清单复选框无法勾选/状态不保存JavaScript 未正确加载或localStorage操作失败1. 检查浏览器控制台是否有 JS 错误。2. 确保GroceryList.astro组件中的客户端脚本 (script) 或client:load指令已正确添加。3. 检查weekKey的生成逻辑确保每周唯一。三阶段指令颜色没有循环或显示错误tailwind.config.mjs中的instructionPalette配置错误或colors.ts逻辑有误1. 检查色板数组格式是否正确颜色值是否为有效十六进制码。2. 运行npm run dev并检查终端是否有Tailwind编译错误。3. 在浏览器开发者工具中检查渲染出的元素看应用的CSS类名是否正确。6.2 样式与构建问题问题现象可能原因解决方案修改了tailwind.config.mjs但样式未更新Tailwind 未重新生成样式1. 停止开发服务器重新运行npm run dev。2. 删除node_modules/.cache目录然后重新启动。生产构建后网站样式丢失Tailwind 的 PurgeCSS或 Astro 的内容集合配置可能过于激进移除了未使用的样式1. 检查tailwind.config.mjs中的content配置确保它包含了所有可能使用Tailwind类名的文件路径如./src/**/*.{astro,html,js,ts,md}。2. 如果使用了动态拼接的类名如bg-${color}-100确保这些颜色名称在safelist配置中列出防止被清除。打印页面布局错乱public/print-config.json配置有误或未被正确加载1. 检查JSON文件格式是否正确没有语法错误。2. 在打印预览的页面中打开开发者工具检查网络标签页确认print-config.json文件是否成功加载状态码200。3. 检查printGenerator.ts中读取和解析配置的代码逻辑。6.3 部署与访问问题问题现象可能原因解决方案推送代码后网站没有更新GitHub Actions 构建失败1. 在 GitHub 仓库的 “Actions” 标签页中查看最新工作流的运行状态和日志。2. 常见原因依赖安装失败网络问题、构建脚本错误如TypeScript编译报错。3. 检查package.json中的build脚本是否正确。网站可以访问但显示404或空白页GitHub Pages 未正确设置源分支或dist目录内容为空1. 进入仓库 Settings - Pages确认 “Source” 设置为 “Deploy from a branch”分支为gh-pages。2. 检查gh-pages分支是否有内容或 Actions 日志是否显示成功推送到了该分支。3. 确保astro.config.mjs中的site和base配置正确对于项目页面base通常是/仓库名/。6.4 高级自定义技巧添加新的餐食分类如果你想在“快速预览”代号中加入新的分类如InstantPot表示需要用到压力锅你需要在weekParser.ts中更新解析逻辑确保能识别这个新代号。在MealCard.astro或相关的展示组件中为这个新代号定义对应的显示样式如特定的图标或背景色。在tailwind.config.mjs中可以考虑为这个分类定义专属的颜色通过instructionSubsections.overrides或者让它使用现有色板循环。支持多语言系统目前是英文导向的。要支持中文或其他语言你需要修改weekParser.ts中的解析逻辑使其能识别不同语言的标题例如同时识别#### Ingredients:和#### 食材:。这可以通过配置一个关键词映射表来实现。将网站上的固定文本如“Grocery List”、“Print”提取为配置变量或使用i18n库。注意这属于较大改动需要仔细测试解析器的兼容性。接入外部食谱API如果你不想手动写Markdown可以改造系统让它从其他食谱网站或API如 Spoonacular拉取数据并自动生成结构化的FOOD-OF-THE-WEEK.md文件。这需要编写一个额外的构建脚本在npm run build之前运行完成数据获取和文件生成。这个“Food of the Week”系统已经稳定运行了相当长一段时间它彻底改变了我家的晚餐规划方式。从最初的简单列表迭代到现在这个功能齐全的协作平台最关键的一点是始终围绕真实的工作流进行设计。技术是为需求服务的找到那个让你和家人感到“痛”的点然后用最合适的技术去解决它这个过程本身带来的满足感不亚于做出一顿美味的大餐。如果你也打算构建类似工具我的建议是先从最简单的文本文件开始明确核心流程然后再用代码去封装和增强它而不是一开始就追求大而全的功能。