两天时间，用 Astro 完成了一个中小型 Blog + 微互动网站，从设计到上线。中间经历了无数的「坑」，但也有一些心得体会，分享给大家。
一、做项目的主人，一定要提前做好整体规划
这个项目的整体设计是：
一个聚焦心理学、技术、人文的内容网站，包含几个模块：
- 整体介绍：网站介绍、博主介绍
- 心理健康：第三方平台精品文章引用、个人博客、心理小应用或测试
- 技术前沿：第三方平台精品文章引用、个人博客、AI 小应用或测试
- 文化探寻：第三方平台精品文章引用、个人博客
AI 时代很难让 AI 帮你做完整的需求设计，只有自己想清楚了，开发效率才会更高。
Tips：可以与 AI 智能体进行需求澄清，这个环节建议 must to be done，会大大提升开发效率。
应用场景想清楚后，IT 架构实现就会更容易一些。可以从下面这些问题入手：
- 这个站点的核心目的是什么？ 是个人品牌展示、内容沉淀，还是希望未来有一定读者规模？这会影响首页的呈现重点和后续是否要做 SEO、订阅等功能。
- 三个栏目的更新频率和内容量大概是什么样？ 每周一篇，还是不定期零星更新？引用是手动整理链接，还是自动抓取第三方平台内容？这决定了内容管理方式。
- 「精品文章引用」具体怎么呈现？ 每篇文章做一个卡片（标题 + 来源 + 简短摘要 + 外链），还是只放一个链接列表？是否需要设计一个固定的卡片模板？
- 「个人博客」是长文还是短文？ 如果是长文，可能需要文章详情页、目录、阅读进度等；如果是短文，直接列表展示即可。
- 引流类的「AI 小应用」是什么形态？ 纯前端交互，还是需要调用后端 API？测试结果需要保存或分享吗？这决定了技术复杂度，也决定了服务器要不要跑后端。
- 人文栏目的内容形态。 历史、文化、旅游——是以游记为主，还是读书笔记、历史随笔？有没有图片展示需求？
- 移动端优先级。 受众主要用手机还是电脑访问？这影响布局设计的取舍。
- 三个栏目页的结构是否统一？ 都是「顶部介绍 + 三个子模块区块」，还是每个栏目有独特布局？
- 博客文章用什么方式写？ Markdown 文件放在项目里，还是接一个 CMS？
- 是否需要评论、订阅、搜索功能？ 这些是后期功能，但初期规划时可以先留位置。
- 小测试的数据要不要存？ 如果只是本地算结果，那纯前端就够了，服务器压力小很多。
二、技术选型很关键，谋定而后动
前端 + 轻互动的技术路线很多。我的诉求是各栏目配置独立、减少耦合。基于这个前提：
- 排除 Gradio：它本质是快速 Demo 工具，不适合做内容站点。
- 排除 HTML + CSS + JS：维护成本高，内容多了会失控。
- 值得考虑 Astro 和 Hugo。
Astro 对 Markdown/MDX 支持成熟，第三方文章引用可以直接用 MDX 嵌入，或者做简单的卡片组件手动维护。如果未来想接 CMS，也有现成集成。需要注意的是，Astro 的构建速度不如 Hugo，但站点规模不大，可以忽略。
我也针对 Hugo 做了考量。Hugo 的核心优势是极快和极简：单一二进制文件，无依赖，Markdown 写作体验流畅，配置清晰。但 Hugo 的局限在于，做心理测试、AI 小应用这类需要深度交互的模块时，不如 Astro 灵活，会需要用 iframe 或外挂 JS，增加了耦合。
最终选 Astro。
三、云上部署是必选项，上云方案要提前考虑清楚
部署方案有两个方向。
方案一：ECS 云服务器（更灵活）
买一台大陆区域的 ECS，装 Nginx 或 Caddy，把 Astro 构建好的 dist 文件夹传上去，配好域名解析。好处是后续心理测试、AI 小应用如果需要跑一个轻量后端（比如调 API 隐藏 Key），这台服务器能直接承接。备案也依赖这台 ECS。
方案二：OBS 对象存储静态托管（更轻量）
OBS 支持直接托管静态网站：创建桶、上传文件、开启「静态网站托管」、绑定自定义域名。不需要自己维护服务器，费用按存储量、请求次数和流量计费，初期访问量不大时成本很低。缺点是只能跑纯静态内容，动态功能需要另外想办法。
最后的建议是用 ECS。 备案绑定了这台服务器，后续扩展空间也更大。OBS 可以作为后续 CDN 回源或备份方案。ECS 的选型很关键，后续扩展性会好很多。
踩过的坑：之前考虑过把 Astro 构建后部署到 Cloudflare Pages（免费），静态资源由 Cloudflare 全球边缘节点分发。国内访问 Cloudflare 通过优选 CNAME/IP 可以显著改善，香港 VPS 作为回源或直接托管，延迟对中国大陆用户通常在 30-50ms。但折腾了很久，后来发现，计算 + 存储 + 项目构建 + 托管等统一选一个云服务厂家效率最高。虽然多花一点钱，但比起部署后的折腾，这点投入真不算什么。
四、以终为始考虑细节
以「第三方文章精选」设计为例。网站初期不可能设计得过于复杂，而且第三方平台内容以引流为主，但要考虑用户的旅程，不能点击之后直接跳出网站，体验也不好。
有三种处理方式：
方式一：新标签页打开
点击链接时用 target="_blank"，浏览器会新开一个标签页，网站还留在原来的标签页里。用户看完外部文章，关掉新标签页就回到我的网站了。这是内容站最常用的做法，简单、无副作用。
方式二：加一个「返回」提示
在外部链接旁边加个小箭头图标，暗示「这是外部链接，会新开页面」。用户有心理预期，不会觉得被打断。
方式三：做中间页
点击后先跳到一个中间页面，显示「即将离开本站，前往 XXX」，几秒后自动跳转，或者用户点确认再跳。这个做法更重，一般用于需要明确告知用户的场景，个人内容站很少用。
综合建议：方式一 + 方式二。 外部链接都用新标签页打开，同时加一个小的外部链接图标，让用户知道「这是要跳出去的」。这样既不会丢失用户，又有清晰的视觉提示。
再举一个例子，就是内容的层次化设计。针对每个栏目设计旅程如下：
第三方文章引流 → 个人博客增强认知 → AI 小应用/互动升华。
先给外部精选内容，再展示自己的原创文章，最后是互动体验。逻辑上从「轻」到「重」。
五、开源生态兼容难题，功能永远在路上，但办法总比困难多
开发中遇到的版本冲突，通常逃不出以下三类。
1. Node.js 与 Astro 本身不兼容
这是最直接的报错，通常因为 Astro 版本升级后，其底层的 Node.js 版本要求也变了。
典型场景：在本地跑得好好的项目，在 CI 构建时失败，报错提示当前 Node.js 版本不被支持。例如，Astro 6 要求 Node.js >= 22.12.0，如果环境是 Node 20 就会失败。
建议方案：遇到这类明确的版本要求报错，最直接的做法是去 package.json 里查看 engines 字段，或查阅对应版本的升级文档，然后把 Node.js 环境切换过去。
2. Node.js 与依赖包（插件）不兼容
这是更常见但更隐蔽的问题。项目依赖的某个第三方包没有及时适配正在使用的 Node.js 新版本。
典型场景：习惯性地把本地 Node.js 升到了最新版（比如 v24），结果运行时控制台疯狂刷 EBADENGINE 警告，提示某个深层依赖只支持到 Node 22。
建议方案：不要盲目追求最新的 Node.js 版本。对于博客这类项目，使用 Node.js 的 LTS（长期支持版）通常是兼容性最好的选择。如果警告不影响程序运行，可以暂时忽略；如果导致构建失败，就需要把 Node.js 切回一个更成熟的版本。
3. 生态链工具的级联限制
Astro 依赖 Vite 和各类官方适配器（如 @astrojs/node），这些工具对 Node.js 的要求会「传导」到项目上。
典型场景：使用了 Node.js 适配器，但发现 Astro 核心与适配器对 Node 版本的要求不一致，导致构建出错。
建议方案：保持 Astro 及其官方适配器版本同步更新。升级 Astro 时，记得一并更新 @astrojs/node 等适配器，它们通常在同一版本周期内保证相互兼容。
再举一个例子。在 Astro 里，「图片和文章同目录」这个体验，目前没有官方开箱即用的方案。业界主流的静态站点生成器大多采用这几种模式：
- 图片放
public/或static/：写作和图片分开，零配置 - 图片放
src/assets/：写作和图片分开，构建时优化 - 图片用图床：写作和图片分开，但图片不受项目结构限制
「图片跟文章同目录」在本地写作工具里比较常见（比如 Obsidian、Typora），但在网站构建工具里比较少见，因为网站构建时对图片有优化、压缩、格式转换等需求，统一管理更方便。
最后采用了折中的方案：通过命名把 blog 内容和 blog 中的图片对应起来，但还是分散在两个目录中。算是一个小遗憾，希望未来 Astro 新版本能够解决这个小 bug。比如：
- 文章：
src/content/tech/zh/年-月-日-llm-engineering-notes.md - 图片：
public/images/tech/zh/年-月-日-llm-engineering-notes-cover.jpg
Astro 渲染网页时，会默认调用 MD 的文件名。有一个小技巧：通过函数处理，可以把文件名中的日期自动去掉，方便在内容创作过程中对存量和增量的内容一目了然，也算是一个小优化。
六、充分用好 MaaS / Token，不用从头造轮子
在设计小程序时，之前想过通过算法写死的方式，但这种测试小程序的效果很差，太小儿科，引流和驻留效果不好。因此想通过大模型 API 的方式引入动态测算，每次题目都不一样，测试结果的解读也更好。
很自然的一个方式是从 Hugging Face 上找模型做小应用，最大的诱惑是「好玩」和「开箱即用」。但有几个细节需要考虑：
- 模型体积与加载速度：网站是 Astro 静态站，部署在 ECS 上。如果直接在前端加载一个 HF 模型（比如通过 Transformers.js），用户首次访问需要下载几十 MB 甚至上百 MB 的模型文件。
- 是否真的「纯前端」：要真正实现模型在用户浏览器运行，需要用到 WebGPU 技术。虽然 Chrome 等现代浏览器已支持，但 Firefox 默认还处于实验阶段，移动端支持也不完全。受众可能来自不同设备，兼容性是个问题。
- 备用方案与成本：更稳妥的做法是用 HF Spaces 的 Serverless API。但这涉及到 API 调用配额，HF 免费的推理请求有速率限制，可能不足以支撑引流。如果需要更高配额，则需要开通 HF Pro。
综合各类因素，最终定下「不本地部署、通过 API 调用」的路线，采用了 MaaS 方案。正好就是这个定位：
- 开箱即用：预置了 GLM、DeepSeek 等主流模型，一键开通，不需要自己部署和运维。
- 按量付费：按实际调用的 Tokens 收费，不用不产生费用，非常适合初期流量不大的引流工具。
- 生态闭环：网站部署和模型调用都在同一个云厂家内，整个技术栈统一，管理起来最省心。
一个小技巧：针对测试题目，采用了更稳的做法——「静态骨架 + 动态内容」：
- 题目结构固定：7 道题，每题 4 个选项，选项分值 1-4 分
- 题目内容动态：模型只负责生成 7 道符合情绪自评主题的题，返回结构化数据（JSON）
- 评分逻辑固定：本地算分，模型不参与算分，避免它算错
- 解读动态：把总分 + 用户答案发给模型，让模型生成一段个性化解读
这样，模型只做它擅长的事（生成文本），不碰它不擅长的事（精确算分）。质量可控，速度也能接受。
七、写在后面
最近看到一个很有意思的数据，来自非营利机构 METR 的随机对照实验。他们让 16 位资深开源开发者处理自己项目里的 246 个真实任务（平均每个耗时约 2 小时），随机分配是否允许使用 AI。结果很反直觉：
- 实测慢了 19%：允许使用 AI 时，完成任务平均多花 19% 的时间。
- 感觉快了 20%：实验前他们预测能提速 24%；哪怕实测已经证明变慢，他们事后依然觉得 AI 帮自己提速了 20%。
为什么会出现这种偏差？
在那些你非常熟悉的复杂项目里，AI 反而可能成为负担：
- 交互成本高：写提示、审查代码、等结果、纠错，这些「沟通」时间反而挤占了真正写代码的时间。
- 熟悉度反噬：资深开发者对代码库有自己的「心流」，AI 的介入反而打断节奏。他们花时间判断「AI 对不对」，不如直接自己写快。
- 复杂项目水土不服：实验用的是维护了 10 年、超百万行代码的开源库。这种有大量隐性规则的项目，AI 往往抓不住重点。
这个结论特指资深开发者处理自己极其熟悉的复杂项目。如果你是在学新东西、做快速原型，或维护不熟悉的代码库，AI 的「提速感」和实际效果可能都会好很多。
这次利用国庆假期，花了两天时间，用 Astro、JSON、TS、JS、MD 等，8000+ 行代码，AI Spec coding，让以前不怎么爱编程的我体验了一把 AI coding 提速的经历，总的感受还是值得期待的。篇幅有限，还有很多内容未详细总结，大家可以亲自实践——实践出真知。