使用 AstroWind 从零搭建并部署一个 Astro v7 + Tailwind CSS v4 网站：完整实战指南

• 前端
• UI组件

AstroWind 是一个免费开源的 Astro 模板（仓库位于GitHub_Trending/as/astrowind），基于 Astro v7 与 Tailwind CSS v4，内置博客、暗色模式、图片优化与 SEO 元数据体系，所有页面都由带类型的组件（widget）拼装而成。本指南以仓库中的官方文档 get-started-website-with-astro-tailwind-css.md 为主线，带你从空文件夹出发，完成「创建项目 → 修改站点配置 → 编辑首页 → 发布第一篇博客 → 构建 → 部署」的全流程；读完你不仅能跑起一个本地可编辑的站点，还能掌握 AstroWind 每个关键配置项背后的源码实现，具备独立定制与部署的能力。

运行 AstroWind 需要什么

在动手之前，先确认环境满足模板的最低要求：

• Node.js 22 及以上：package.json中的engines字段明确写死了最低版本"node": ">=22.22.3"（见 package.json）。安装后用node -v确认版本即可，不需要额外依赖.nvmrc。
• 一个终端和一个编辑器：Visual Studio Code 配合官方 Astro 扩展，可以在.astro文件里获得语法高亮与补全。
• 一个 GitHub 账号：仅在最后使用「一键部署」时用到，本地开发不强制。

用一条命令创建你的 Astro + Tailwind 项目

Astro CLI 可以直接从任意 GitHub 仓库脚手架项目。在终端执行：

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

按提示回答几个问题（项目文件夹名、是否安装依赖、是否初始化 git），然后进入项目目录并启动开发服务器：

cd my-site npm run dev

浏览器打开http://localhost:4321，你看到的就是完整的演示站点：一个首页、多个备选首页（src/pages/homes/）、一组落地页（src/pages/landing/）、一个演示博客，以及常见的 about、services、pricing、contact 和法务页面。你看到的每一个区块都对应一个可编辑的文件，开发服务器会在保存时自动热更新。

值得注意的一点：该命令在仓库首页组件 src/pages/index.astro 的 QuickStart 组件中同样被写为「一条命令完成全部初始化」，是模板官方推荐的唯一入口方式。

AstroWind 模板：东西都放在哪

你几乎所有时间都会待在src/目录下。官方文档给出的核心目录对照如下，我补充了仓库中的实际位置：

模板自身的「机器」放在vendor/integration/（一个名为astrowind的 Astro 集成，在 astro.config.ts 中通过astrowind({ config: './src/config.yaml' })挂载，负责把 YAML 配置注入到astrowind:config虚拟模块），日常开发不需要改动它。

起步三件套：最先改的三个文件

1.src/config.yaml：站点身份与 SEO 默认值

官方文档要求你至少改三处：site.name、site.site（最终部署的 URL，sitemap、RSS、Open Graph 标签都依赖它），以及默认metadata.title和metadata.description。仓库中完整的 src/config.yaml 结构如下，其中注释为配置项说明：

site: name: AstroWind # 站点名称 site: 'https://astrowind.vercel.app' # 正式 URL，部署后要改成真实地址 base: '/' # 站点根路径，子目录部署时修改 trailingSlash: false # 是否生成带尾部斜杠的 URL googleSiteVerificationId: orcPxI47GSa-cRvY11tUe6iGg2IO_RPvnA1q95iEM3M # 默认 SEO 元数据 metadata: title: default: AstroWind template: '%s — AstroWind' # %s 会被页面级标题替换 description: "..." robots: index: true follow: true openGraph: site_name: AstroWind images: - url: '~/assets/images/default.png' # 默认社交分享图 1200x628 width: 1200 height: 628 type: website twitter: handle: '@arthelokyo' site: '@arthelokyo' cardType: summary_large_image i18n: language: en # 站点语言（sitemap 与结构化数据会用到） textDirection: ltr # 支持 RTL apps: blog: isEnabled: true # false 则整个博客、RSS、文章组件都不进入构建 postsPerPage: 8 # 列表每页文章数 post: isEnabled: true permalink: '/%slug%' # 可用变量：%slug% %year% %month% %day% %hour% %minute% %second% %category% %id% robots: index: true list: isEnabled: true pathname: 'blog' # 博客列表路径，可改为 "articles" robots: index: true category: isEnabled: true pathname: 'category' # 分类路径，如 /category/some-category robots: index: true tag: isEnabled: true pathname: 'tag' # 标签路径，如 /tag/some-tag robots: index: false isRelatedPostsEnabled: true relatedPostsCount: 4 analytics: vendors: googleAnalytics: id: null # 填入 "G-XXXXXXXXXX" 即启用 ui: theme: 'system' # 可选：system | light | dark | light:only | dark:only

几个值得注意的实现细节：

• permalink变量在 src/utils/blog.ts 的generatePermalink中逐项替换，年份/月/日/时分秒取自文章的publishDate，因此/%year%/%month%/%slug%/这种带日期的模式可以直接使用。
• 关闭博客只需apps.blog.isEnabled: false，此时 src/utils/blog.ts 导出的isBlogEnabled等开关会让博客路由、RSS、相关文章与文章组件全部从构建中消失，其余页面不受影响。
• Google Analytics的注入由public/_headers与 src/components/common/Analytics.astro 协作完成，配置analytics.vendors.googleAnalytics.id即可启用。

2.src/navigation.ts：导航菜单与页脚

把演示菜单换成你自己的页面。每个条目都是{ text, href }结构，内部链接务必用getPermalink('/about')生成，这样如果将来部署在子目录下，基础路径会被正确保留。仓库中的 src/navigation.ts 导出headerData（links支持带子菜单的分组，actions是按钮）和footerData（多栏links、secondaryLinks、socialLinks、footNote）。

getPermalink的实现在 src/utils/permalinks.ts：它会自动拼接SITE.base，并按照trailingSlash配置决定是否补斜杠；对http(s)://、#开头的链接则原样返回。同文件还提供了getBlogPermalink()、getAsset()（用于/rss.xml这类静态资源）等便捷函数，页脚里的 RSS 链接正是这样生成的（见 src/navigation.ts）。

3.src/components/CustomStyles.astro：品牌色与字体

这是整个模板的「主题中枢」。仓库中的 src/components/CustomStyles.astro 定义了两组 CSS 变量，一组在:root（亮色），一组在.dark（暗色）：

:root { --aw-font-sans: var(--font-inter); --aw-font-serif: var(--font-inter); --aw-font-heading: var(--font-inter); --aw-color-primary: rgb(1 97 239); --aw-color-secondary: rgb(1 84 207); --aw-color-accent: rgb(109 40 217); --aw-color-text-heading: rgb(0 0 0); --aw-color-text-default: rgb(16 16 16); --aw-color-text-muted: rgb(16 16 16 / 66%); --aw-color-bg-page: rgb(255 255 255); }

暗色模式只需在.dark块里覆盖同一组变量（如背景换成rgb(8 9 10)），模板里所有组件都读取这些变量，所以改品牌色实际上就是改这几个rgb(...)值。

字体不在这个文件里，而是通过 Astro 的原生 Fonts API 声明在 astro.config.ts：fonts条目使用fontsourceprovider 引入 Inter，权重区间100 900、子集latin，并注入 CSS 变量--font-inter；CustomStyles.astro再把--aw-font-*指到--font-inter。想换字体就改fonts条目并重指--aw-font-*。此外这些主题变量还会同步喂给 shadcn/ui 兼容的 design tokens（bg-background、text-foreground等，见 src/assets/styles/shadcn.css），所以 shadcn 风格组件会自动继承你的主题。

编辑首页：布局 + 组件堆叠

打开src/pages/index.astro。一个页面 = 一个布局 + 一组带 props 的 widget。官方文档给出了最小可用的示例：

--- 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: invoices without the spreadsheet', description: 'Send, track and reconcile invoices in one place.', }; --- <Layout metadata={metadata}> <Hero tagline="Invoicing" title="Invoices without the spreadsheet" subtitle="Send, track and reconcile in one place." actions={[{ variant: 'primary', text: 'Start free', href: '#pricing' }]} image={{ src: '~/assets/images/hero-image.png', alt: 'Product screenshot' }} /> <Features id="features" title="What you get" items={[ { title: 'Recurring invoices', description: 'Set it once.', icon: 'tabler:repeat' }, { title: 'Payment links', description: 'Card or bank transfer.', icon: 'tabler:credit-card' }, ]} /> <CallToAction title="Ready?" actions={[{ variant: 'primary', text: 'Start free', href: '/signup' }]} /> </Layout>

要点说明：

• 大多数区块组件共享同一套基础 props：title、subtitle、tagline、用于锚点定位的id，以及用于自定义背景的bgslot（仓库首页里QuickStart、FAQs等组件都通过<Fragment slot="bg">传入自定义渐变背景，见 src/pages/index.astro）。
• 图标来自 Tabler 图标集，通过astro-icon集成以tabler:xxx形式引用；图标集白名单配置在 astro.config.ts。
• 组件内部的~别名指向src/目录，配置见 astro.config.ts。
• 想知道每个 widget 的全部 props 与演示用法，可以直接读src/components/widgets/下的源码；src/pages/landing/里的 6 个落地页（lead-generation、sales、click-through、product、pre-launch、subscription）展示了多个 widget 组合成完整页面的最佳实践。

真实的仓库首页远比示例丰富：它由 Hero、SocialProof、QuickStart、Features、Content×3、Steps、Features2、Timeline、Note、BlogHighlightedPosts、FAQs、Stats、CallToAction 等十几个 widget 按顺序堆叠而成（见 src/pages/index.astro），并额外注入了StructuredData（WebSite+Organization的 JSON-LD 结构化数据），这正是「参考真实页面学习组合方式」的最好范本。

发布你的第一篇博客

在src/data/post/下新建hello-world.md：

--- publishDate: 2026-08-24T00:00:00Z title: Hello, world excerpt: The first post on the new site. image: ~/assets/images/hello.jpg imageAlt: The team at the launch party category: News tags: - company author: Your name --- Write in Markdown. Headings, lists, tables, code blocks and images all work; use the `.mdx` extension to embed components.

文章会自动出现在/hello-world（具体模式由config.yaml的apps.blog.post.permalink决定）、博客列表、分类页、标签页、RSS 和 sitemap 中，Open Graph 标签与结构化数据（BlogPosting）也会自动生成。

这些 frontmatter 字段全部由 src/content.config.ts 中的 post 集合 schema 约束，除示例中的字段外还支持：

• draft: true：草稿不会进入构建。对应 src/utils/blog.ts 中load()的.filter((post) => !post.draft)逻辑。
• updateDate：修订日期，会显示在标题下方并告知搜索引擎内容已更新。
• metadata：覆盖默认 SEO 的对象（canonical、robots、openGraph、twitter等），与config.yaml的metadata结构一致。
• .mdx扩展名：允许在文章中直接嵌入组件。

另外两处由源码保证的细节：阅读时间由 src/utils/frontmatter.ts 的readingTimeRemarkPlugin在构建时自动计算（基于reading-time库）；表格会被responsiveTablesRehypePlugin自动包一层overflow:auto的容器，避免窄屏溢出。想预览每种 Markdown 元素的渲染效果，可以参考仓库中的 markdown-elements-demo-post.mdx。

检查与构建

npm run check # astro check、ESLint 和 Prettier 三合一检查 npm run build # 生成 dist/ 静态站点 npm run preview # 在本地预览 dist/

npm run check在 package.json 中被定义为check:astro（astro check，含类型检查）、check:eslint、check:prettier的串联；npm run fix则直接自动修复 ESLint 与 Prettier 问题。构建产物是纯静态的：dist/就是一堆 HTML、CSS、JavaScript 和优化后的图片，任何能托管静态文件的 Web 服务器都能直接挂载。构建管线中还集成了astro-compress（CSS 用 lightningcss 压缩，JavaScript 压缩，见 astro.config.ts）与 sitemap 生成。

部署：Vercel、Netlify、Cloudflare 与自有服务器

• Vercel 或 Netlify：连接仓库后两者都能自动识别 Astro，执行npm run build并把dist/作为输出目录。
• Cloudflare Pages、GitHub Pages 或任意静态托管：直接把dist/上传即可；如果需要子目录部署（base path），在config.yaml的site.base中设置即可，getPermalink会自动把基础路径拼进所有内部链接。
• 自有服务器：仓库自带一个多阶段构建的 Dockerfile：node:lts安装依赖 →npm run build→ 最终用nginx:stable-alpine镜像把dist/拷进/usr/share/nginx/html并挂载 nginx/nginx.conf。该 nginx 配置监听8080端口，开启了 gzip 压缩（text/css、application/javascript、application/xml+rss等），并把 404 指向404.html。构建镜像即可：docker build -t astrowind . && docker run -p 8080:8080 astrowind（仓库还附带 docker-compose.yml 可一键编排）。

首次部署完成后，如果还没设置过，记得把config.yaml里的site.site改成真实 URL——canonical 链接、sitemap 和社交分享预览图都依赖它指向正确地址。

下一步：继续深入的方向

• 品牌化定制：颜色、字体、Logo、favicon 的完整指南见 how-to-customize-astrowind-to-your-brand.md。
• 模板底层原理：integration、permalink、图片与元数据机制见 astrowind-template-in-depth.mdx。
• 打造高转化落地页：6 个落地页示例背后的设计思路见 landing.md。
• 配合 AI 编程助手：仓库根目录的 AGENTS.md 与 CLAUDE.md 记录了项目约定，Claude Code、Cursor 等工具可以据此遵循模板规范完成任务——这也是 AstroWind 被称为「AI-ready」的原因。

• 前端
• UI组件