用 AstroWind 上手，基于 Astro 和 Tailwind CSS 做网站

AstroWind 是一套免费、开源的模板，给 Astro 和 Tailwind CSS 用。它给你一个完整的营销站：带博客、深色模式、优化过的图片和 SEO 元数据，页面由带类型的组件拼出来。这篇指南带你从空文件夹走到部署上线，一步一步来。如果你不想自己敲这些步骤，模板已经为 AI 编程助手准备好了：可以把活交给 Claude Code、Cursor 或类似的工具，想知道它动了什么，再回到这里。

你会做出什么

• 一份能在本地跑起来的模板，上面是你的名字、颜色和菜单。
• 用模板里的小组件拼出的首页。
• 你的第一篇博客：出现在列表里，带上标签，并写进 RSS。
• 一份部署出去的静态构建，可以放到 Vercel、Netlify，或任何能托管文件的主机上。

跑 Astro 需要什么

• Node.js 22。 package.json 里的 engines 写了最低版本；.nvmrc 锁的是主版本，所以 nvm use 会给你一个兼容的版本。
• 一个终端和一个编辑器。Visual Studio Code 加上 Astro 扩展，在 .astro 文件里会有高亮和补全。
• 如果想用文末的一键部署，需要一个 GitHub 账号。

创建 Astro 和 Tailwind 项目

Astro 的命令行可以从任意 GitHub 仓库拉出一套项目：

npm create astro@latest -- --template arthelokyo/astrowind

按提示回答（项目文件夹、是否安装依赖、是否初始化 git），然后：

cd my-site
npm run dev

打开 http://localhost:4321。你看到的是演示站：一个首页、几套备用首页、一组落地页、一个演示博客，以及常见的关于、服务、价格、联系和法律页面。你看见的每一块都是可以改的文件，开发服务器会在保存时重新加载。

AstroWind 模板里东西放在哪

你绝大部分时间都会待在 src/ 里：

模板自己的机关在 vendor/integration/。你不用去动它。

最先改的三个文件

src/config.yaml。 改 site.name 和 site.site（你的最终网址，站点地图、RSS 和 Open Graph 标签都要用），然后改默认的 metadata.title 和 metadata.description。apps.blog 这一段管博客：不想要博客就设 isEnabled: false，也可以改 postsPerPage 和 permalink 模式。

src/navigation.ts。 用你自己的页面换掉演示菜单。每一项是 { text, href }；站内链接用 getPermalink('/about')，这样以后部署到子目录时，base 路径仍然对。

src/components/CustomStyles.astro。 你的品牌色：--aw-color-primary、--aw-color-secondary 和 --aw-color-accent，再加上文字色和背景色，浅色一份、深色一份。模板里的东西都读这些变量。字体在 astro.config.ts 里声明（fonts 那一项，由 Astro 的 Fonts API 提供），再在 CustomStyles.astro 里映射到 --aw-font-* 变量。定制指南把这些讲得更细。

改首页

打开 src/pages/index.astro。一个页面就是一个布局，加上一叠小组件，每个小组件用 props 来配置：

---
import Layout from '~/layouts/PageLayout.astro';
import Hero from '~/components/widgets/Hero.astro';
import Features from '~/components/widgets/Features.astro';
import CallToAction from '~/components/widgets/CallToAction.astro';

const metadata = {
  title: 'Acme：不用表格也能管发票',
  description: '在一个地方发送、跟踪和对账。',
};
---

<Layout metadata={metadata}>
  <Hero
    tagline="开票"
    title="不用表格也能管发票"
    subtitle="在一个地方发送、跟踪和对账。"
    actions={[{ variant: 'primary', text: '免费开始', href: '#pricing' }]}
    image={{ src: '~/assets/images/hero-image.png', alt: '产品截图' }}
  />

  <Features
    id="features"
    title="你会得到什么"
    items={[
      { title: '周期性发票', description: '设一次就行。', icon: 'tabler:repeat' },
      { title: '付款链接', description: '银行卡或银行转账。', icon: 'tabler:credit-card' },
    ]}
  />

  <CallToAction title="准备好了吗？" actions={[{ variant: 'primary', text: '免费开始', href: '/signup' }]} />
</Layout>

多数区块小组件共用同一组基础 props：title、subtitle、tagline，用来做锚点的 id，以及放自定义背景的 bg 插槽。图标来自 Tabler，通过 astro-icon 使用。区块小组件有哪些、主要 props 是什么、各自在哪个演示页出现，写在 .agents/skills/use-widgets.md。src/pages/landing/ 下面的落地页把它们拼成完整页面，落地页指南讲的是这些页面背后的想法。

发布第一篇文章

创建 src/data/post/hello-world.md：

---
publishDate: 2026-08-24T00:00:00Z
title: 你好，世界
excerpt: 新站点上的第一篇文章。
image: ~/assets/images/hello.jpg
imageAlt: 发布会上的团队
category: 新闻
tags:
  - 公司
author: 你的名字
---

用 Markdown 来写。标题、列表、表格、代码块和图片都可以；
要嵌入组件的话，把扩展名换成 `.mdx`。

文章会出现在 /hello-world（具体模式由 config.yaml 里的 permalink 决定），出现在博客列表、它的分类页和标签页、RSS 和站点地图里，Open Graph 标签和结构化数据会一并生成。draft: true 让文章在你还在写的时候不进入构建；updateDate 标记一次修订，显示在标题下面，也会交给搜索引擎。Markdown 演示文章展示了每种元素渲染出来的样子。

检查并构建

npm run check   # astro check、ESLint 和 Prettier
npm run build   # 静态站点输出到 dist/
npm run preview # 在本地打开 dist/

这次构建是完全静态的：dist/ 是一文件夹的 HTML、CSS、JavaScript 和优化过的图片，任何 Web 服务器都能托管。

部署你的 Astro 站点（Vercel、Netlify、Cloudflare）

• Vercel 或 Netlify： 连上仓库。两边都能认出 Astro，用 npm run build，输出目录是 dist/。README 里有这两个以及其他主机的一键按钮。
• Cloudflare Pages、GitHub Pages，或任何静态主机： 上传 dist/。.agents/skills/ 里的 deploy-cloudflare 和 deploy-with-base-path 覆盖了两种需要额外设置的情况。
• 你自己的服务器： 仓库里有一份 Dockerfile，用 nginx 提供 dist/。

第一次部署之后，如果还没改过，把 config.yaml 里的 site.site 设成真实网址，这样规范链接、站点地图和社交预览才会指向对的地方。

接下来

• 把模板改成你的品牌：颜色、字体、logo、favicon。
• 模板内部是怎么工作的：集成、永久链接、图片和元数据。
• 做一页能转化的落地页：六套落地页示例背后的那篇指南。
• 在用 AI 编程助手？仓库里有 AGENTS.md，.agents/skills/ 里是逐步的 skill，助手会按模板的规矩来。怎样让它发挥得更好。