astro-dev

Astro 开发

以项目已安装的 Astro 版本和本地约定为准。本技能中的参考资料介绍了当前 Astro 7 的模式和常见迁移陷阱；除非用户提出要求，否则不要据此进行大范围重构。

快速开始

1. 阅读 package.json、锁定文件、astro.config.* 和目标文件。
2. 确认与任务相关的已安装 Astro、Node、适配器、集成和内容配置。
3. 根据下面的路由表，只阅读对应的参考资料。
4. 对于依赖版本或不熟悉的 API，使用可用的官方文档功能，在 Astro 官方文档中核实其当前的准确行为。只有在需要查询时才阅读 references/doc-endpoints.md。
5. 以最小改动完成所请求的结果，并遵循代码库中的组件、样式和部署约定。
6. 运行相关的类型检查、检查、构建和测试命令。对于可见行为，渲染受影响的路由并测试涉及的状态。

参考资料路由表

任务	阅读
项目设置、核心 API、文件结构、脚本、中间件、Astro 7 升级或高级路由	references/astro-core-patterns.md
构建时或实时内容集合、加载器、查询、Zod 4	references/content-collections.md
RSS、分页、标签、SEO、目录、Shiki、Markdown/MDX 自定义	references/blog-recipes.md
Tailwind CSS v4、主题、字体	references/tailwind.md
Islands 和 client:* 水合	references/islands-and-hydration.md
Actions、表单、验证、变更	references/actions-and-forms.md
<ClientRouter />、生命周期事件、状态保留	references/view-transitions.md
预渲染、会话、环境变量、国际化、CSP、缓存、Cloudflare	references/server-features.md
官方文档搜索和备用 URL	references/doc-endpoints.md

不要预先加载所有参考资料。如果任务涉及两个领域，就阅读对应的两份；路由表不是检查清单。

兼容性检查

只检查任务涉及的行。

领域	当前基准
内容	src/content.config.ts；每个集合都必须有加载器；从 astro/zod 导入 z；调用独立的 render(entry)
Tailwind	使用已安装的 Tailwind v4 配置，通常是 @tailwindcss/vite 加 @import "tailwindcss"；不要重新引入已弃用的 @astrojs/tailwind
Markdown/MDX	Astro 7 默认使用 Sätteri；使用 markdown.processor，并根据项目的插件需求选择 Sätteri 或 unified
水合	对需要立即交互的 UI 使用 client:load；对延迟加载的岛屿使用 client:idle 或 client:visible；不要对静态标记进行水合
变更	应用表单优先使用类型化 Actions；需要 Cookie、会话、Actions、POST 处理或每请求数据的页面必须按需渲染
环境变量	应用代码优先使用基于架构的 astro:env；区分构建时的 import.meta.env 与文档说明的运行时／配置时例外情况
ClientRouter	使用 astro:page-load 初始化；对替换后的元素使用事件委托；在 astro:before-swap 中设置绘制前状态
Astro 7	Node 22.12+、Vite 8、ESM 配置；严格 HTML 解析；JSX 空白默认行为；保留名称 src/fetch.ts；顶层缓存和路由规则

不要在新代码中照搬已移除的模式，例如 Astro.glob()、entry.render()、旧版集合位置／类型、output: 'hybrid'、CJS 配置和 <ViewTransitions />。如果迁移涉及这些模式，请使用 references/astro-core-patterns.md 查看完整的对应关系。

实施工作流

1. 明确改动范围

说明所需行为以及可能负责实现它的文件。除非请求明确要求更改，否则应保留公开路由、内容 ID、适配器行为和设计系统约定。不要仅因为 Astro 支持，就添加集成、客户端框架或新的抽象。

2. 选择 API 前先检查

• 检查包管理器脚本和已安装的包版本。
• 检查路由是预渲染还是按需渲染。
• 使用 Node API 或服务端功能前，先检查适配器和运行时。
• 检查现有的内容加载器、Actions、中间件和样式入口。
• 引入新方案前，先在代码仓库中搜索是否已有成熟方案。

3. 在合适的边界实现

让路由文件专注于路由、数据加载和组装。复用现有布局、组件和辅助函数。只有在请求的更改会导致职责混杂或增加验证难度时，才拆分文件；不要把小修复变成全仓库重组。

默认使用服务端渲染的 Astro 标记。只有当浏览器需要状态或即时交互时才添加客户端岛屿，并选择仍能保留预期交互的最不积极的指令。

4. 验证行为

优先使用项目的包管理器和现有脚本。根据更改范围，验证以下内容：

• Astro／类型检查和针对性测试
• 配置、集成、路由或部署更改对应的生产构建
• 在目标运行时中检查受影响路由的服务端行为
• 可见 UI 更改对应的桌面端／移动端渲染和主要交互
• 迁移特有的情况，例如无效 HTML、行内空白、内容 ID、环境时序以及预渲染／按需渲染边界

不要仅凭静态检查就声称升级或 UI 更改已完成。如果环境无法运行相关检查，请明确说明具体缺项。

模板

templates/ 下的文件只是起点，不能替代对代码仓库的检查。仅复制与已安装集成和部署目标兼容的部分。

输出约定

首先说明已完成的行为。然后概述更改涉及的文件范围和实际运行过的检查；如有相关情况，也包括渲染过的路由或视口。指出任何未经验证的运行时、迁移情况或视觉状态。仅在用户提出要求时才添加教程。

注意事项

• 看起来最新的 API 不一定是已安装的 API。编辑前先检查版本，并查阅官方文档以了解确切的版本相关行为。
• 静态 frontmatter 在构建时运行；每次请求都需要执行的逻辑需要按需渲染和合适的适配器。
• class 不会自动传递给 Astro 组件，作用域样式也不会自动应用于插槽／Markdown 内容。
• 经过处理的 <script> 标签会被打包并去重；define:vars 意味着使用行内行为。多个组件实例需要采用实例安全的模式。
• 构建通过并不能证明水合时序、ClientRouter 生命周期或响应式布局没有问题。请实际测试发生更改的行为。
• 避免在用户要求之外顺带进行迁移、添加依赖或拆分文件。