从0-1: 如何用AI搭建一个网站

这是一份面向新手的实践教程。目标不是一次让 AI 生成完整网站，而是把需求拆成可以检查的小步骤，逐步做出一个能运行、能维护、能继续扩充的储能术语站。

本教程以当前项目为准：使用 Node.js 22、Astro 7、TypeScript Strict 和 Tailwind CSS 4，由 Astro 在构建时生成静态页面。术语正文通过 Content Collections 管理，搜索索引也在构建时生成，不依赖数据库和运行时服务。

一、准备开发环境

需要的工具

• Node.js 22：运行本地开发和构建命令。
• 代码编辑器与 AI 编程工具：可以使用 VS Code、Codex 或自己熟悉的工具。
• GitHub：保存代码和版本历史。
• Vercel：用于部署静态站点，也可以换成其他支持 Astro 的平台。

安装后，在终端确认版本：

node -v
npm -v
git --version

如果命令都能正常返回版本号，环境就准备好了。推荐Claude或者Codex。

二、先把需求写清楚

AI 很擅长补全局部代码，却不会自动理解产品边界。开始写代码前，先把目标、页面和不做的内容写成一页需求。

网站定位

这个项目服务于缺少储能和电气背景的数字产品从业者，帮助他们理解行业术语、系统关系和数据含义。内容要说明通用语义和概念边界，不替代工程设计、设备选型、安全规范、厂商文档或当地法规。

页面结构

• 首页：说明网站价值，展示储能场景和常用术语。
• 场景页：解释系统由什么组成，以及设备之间的基本关系。
• 术语索引：按场景和类别浏览已经发布的术语。
• 术语详情：共用一套页面骨架，展示定义、通俗解释、边界、角色视角、相关术语和参考来源。
• Labs：承载 Skill、教程和后续实验内容。

第一版功能

• 深浅主题；
• 响应式布局；
• 全局术语搜索；
• 多场景索引；
• 独立术语详情页；
• 内容校验和构建检查。

可以把下面这段作为 AI 的起始上下文：

请先阅读项目需求，再提出最小可运行版本。使用 Astro、TypeScript Strict 和 Tailwind CSS，优先静态生成，不增加数据库、登录或运行时服务。页面需要支持深浅主题、响应式布局、术语搜索和可复用的术语详情模板。每次只完成一个可验证模块，并说明修改文件和验证命令。

三、初始化 Astro 项目

用 Astro 官方脚手架创建项目，然后安装依赖：

npm create astro@latest energy-dictionary-glossary
cd energy-dictionary-glossary
npm install
npm install tailwindcss @tailwindcss/vite

在 astro.config.mjs 中接入 Tailwind 的 Vite 插件：

import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

启动本地开发服务器：

npm run dev

Astro 默认地址是 http://localhost:4321/。先确认空项目可以打开，再开始添加页面；这样后面出错时，更容易判断是哪一步引入了问题。

四、按模块完成网站

1. 先做全局骨架

先完成基础 Layout、Header、颜色 Token、容器宽度和排版规则。深浅主题的颜色都放在全局语义 Token 中，页面只引用 Token，不在组件里散落颜色值。

建议顺序：

1. BaseLayout：统一页面标题、描述、favicon 和全局结构。
2. SiteHeader：品牌、主导航、搜索、主题切换和作者入口。
3. 全局样式：画布、表面、文字、边框、强调色、间距和圆角。
4. 搜索弹窗：键盘操作、焦点管理和无结果状态。

每完成一步，都在深色、浅色和窄屏下检查一次。

2. 建立术语内容模型

不要把几十个术语直接写进页面。用 Astro Content Collections 存 Markdown，并用 Zod 约束字段。一个术语至少要有：

• 唯一 ID、名称、英文名和类别；
• 摘要、定义和通俗解释；
• 关键边界；
• 不同角色如何理解；
• 相关术语；
• 参考来源和发布状态。

Schema 的价值在于：字段缺失、链接无效或类型错误时，构建会直接失败，问题不会静默进入线上页面。

3. 用一个模板生成详情页

详情页不要按术语复制粘贴。让动态路由读取集合内容，再把数据交给同一套布局组件。设备、系统、状态、策略和指标可以共享阅读骨架，只在需要时切换关系图、状态刻度、目标图或公式卡。

新增术语时，理想流程只有三步：

1. 新增一份术语 Markdown；
2. 新增或更新对应审阅记录；
3. 运行检查并构建。

4. 最后接入搜索

项目在构建时从已发布术语生成轻量搜索索引，浏览器只负责匹配名称、英文名、别名和摘要。对当前内容规模来说，这比数据库或第三方搜索服务更简单，也更容易部署。

五、与 AI 协作的方法

一次只给 AI 一个明确目标，例如“完成 Header 的移动端布局”或“为术语详情增加参考来源卡片”。同时提供：

• 目标页面和文件范围；
• 期望结果；
• 不能改变的部分；
• 验证方式。

每一轮都要求 AI 先读现有实现，复用已有组件和 Token。完成后查看实际页面，再继续下一轮。视觉问题适合用截图标注具体位置；内容问题则直接指出术语、句子和来源。

AI 生成的储能内容只能作为草稿。发布前至少要检查术语边界、统计口径、适用场景和参考来源，不能把厂商特性或地区规则写成行业通用结论。

六、做基础 SEO

当前项目已经为页面设置独立的标题和描述，并通过静态构建输出可直接访问的 HTML。正式发布前继续检查：

• 标题和描述是否准确、是否重复；
• 标题层级是否连续；
• 页面路径是否稳定；
• 图片是否有合适的替代文本和尺寸；
• 正式页面是否允许索引，开发预览页是否设置 noindex。

sitemap.xml、robots.txt、canonical、Open Graph 和结构化数据适合在公开发布前单独实现和验证。不要只让 AI 写一句“已完成 SEO”，要查看构建产物和线上页面是否真的包含对应内容。

七、验证与部署

提交前运行项目已有的三组检查：

npm run check
npm run build
npm run check:regression

• check 检查 Astro 和 TypeScript；
• build 生成静态站点；
• check:regression 验证搜索、主题、正式路由和开发预览隔离等关键行为。

检查通过后，再提交到 Git：

git status
git add <本次确认的文件>
git commit -m "feat: describe the change"
git push origin main

部署到 Vercel 时，导入 GitHub 仓库，使用项目默认的 npm run build。当前项目输出静态文件，不需要数据库、环境变量或 Astro 服务端适配器。以后每次推送都可以触发新构建；是否自动发布到正式域名，取决于你的 Vercel 项目设置。

八、新手最容易踩的坑

• 一次生成整个项目：代码看起来完整，但错误会互相叠加。拆成页面和组件逐个验收。
• 只看聊天里的代码：必须在浏览器中检查真实效果，并运行构建。
• 把预览当成正式页面：开发实验路由应在生产构建中消失，并加上 noindex。
• 术语只有定义，没有边界：相近概念很容易被混用，必须说明“它是什么”和“它不是什么”。
• 来源存在就算完成：链接需要能打开，内容也要真正支持页面里的结论。
• 把 AI 当作审核人：AI 可以帮助整理，最终发布判断仍由人完成。
• 把密钥提交到 GitHub：如果未来使用外部 API，把密钥放在部署平台的环境变量中，并确保本地环境文件不进入版本库。

九、完成第一版之后

第一版不需要覆盖整个储能行业。先让有限的术语具备稳定的内容结构、可追溯来源和一致的阅读体验，再逐步扩展场景。每次扩展都沿用同一流程：定义范围、写内容、校验边界、浏览器检查、构建、提交和部署。

从 0 到 1 的关键不是让 AI 一次写得最多，而是让每一步都有明确结果，能够检查，也能随时回退。