企业官网建设流程全解析

• 前端
• UI组件

导读

在 AstroWind（基于 Astro v7 与 Tailwind CSS v4 的免费开源模板）中，博客文章属于 Astro内容集合（Content Collection），其数据在astro build阶段被一次性编译并烘焙进dist/静态产物。这意味着无论静态托管还是 SSR 模式，运行期都不会再重新读取src/data/post目录——Docker 挂载该目录并运行时追加文件，不会让新文章"自动上线"。本文将结合仓库源码，完整梳理这一构建期模型的底层机制、四种发布新文章的可行方案，以及fetchPosts()缓存与草稿过滤等关键实现细节。

内容集合的构建期加载模型

集合定义：glob()加载器指向src/data/post

AstroWind 的博客内容集合定义在 src/content.config.ts，核心代码为：

const postCollection = defineCollection({ loader: glob({ pattern: ['*.md', '*.mdx'], base: 'src/data/post' }), schema: z.object({ publishDate: z.date().optional(), updateDate: z.date().optional(), draft: z.boolean().optional(), title: z.string(), excerpt: z.string().optional(), image: z.string().optional(), imageAlt: z.string().optional(), category: z.string().optional(), tags: z.array(z.string()).optional(), author: z.string().optional(), metadata: metadataDefinition(), }), }); export const collections = { post: postCollection, };

从源码可以确认两个关键事实：

1. 加载器是glob()：它在构建期扫描src/data/post下的*.md与*.mdx文件，将其解析为集合条目。构建完成后，产物以静态 HTML 形式固化在dist/中。
2. 集合目录是src/data/post：src/content/post目录在 Astro 5 迁移中已被移除，目录结构已随新版 Astro 的 Content Layer 机制调整。仓库中实际存在的文章示例见 src/data/post（如get-started-website-with-astro-tailwind-css.md、markdown-elements-demo-post.mdx等）。

构建期之后的"只读"特性

文档明确指出：astro build之后，没有任何运行时组件会重新读取src/data/post——静态输出不会，SSR 也不会。这是理解本主题的核心前提：内容在构建期"冻结"，运行期不可变。

从实现层面看，这种"冻结"有两处证据：

• SSR 缺失：AstroWind v1 是纯静态模板，未启用按需渲染（on-demand rendering），因此根本没有运行期读取内容的入口；
• 缓存机制（详见下文）：即便未来引入 SSR，fetchPosts()的模块级缓存也决定了同一构建进程内内容只会被读取一次。

构建期模型的直接后果

后果一：Docker 卷挂载不会发布新文章

如果执行类似下面的操作：

docker run -v $(pwd)/src/data/post:/app/src/data/post -p 8080:8080 my-site

运行期向宿主机src/data/post目录中添加.md文件，并不会让这些文章出现在站点上。因为镜像中的dist/已在构建时生成，nginx 只负责把静态产物原样送出，不参与任何内容解析。要发布新文章，必须重新执行构建。

后果二：Dockerfile 的"一次构建、静态托管"模型

仓库自带的 Dockerfile 正是文档所述模型的官方落地实现：

FROM node:lts AS base WORKDIR /app FROM base AS deps COPY package*.json ./ RUN npm install FROM base AS build COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npm run build FROM nginx:stable-alpine AS deploy COPY --from=build /app/dist /usr/share/nginx/html COPY ./nginx/nginx.conf /etc/nginx/nginx.conf EXPOSE 8080

这是一个经典的多阶段构建：

1. deps 阶段：安装依赖（对应package.json中engines.node >= 22.22.3的要求）；
2. build 阶段：执行npm run build（即astro build），把内容集合编译进dist/；
3. deploy 阶段：基于nginx:stable-alpine，将dist/复制到/usr/share/nginx/html，并套用 nginx/nginx.conf。

nginx 配置在 8080 端口提供服务，并通过try_files $uri $uri/index.html =404;支持 SPA 风格的路径回退；同时开启了 gzip 压缩（gzip on; gzip_min_length 1000;）。配套的 docker-compose.yml 将容器 8080 端口映射到宿主机 8080：

services: astrowind: build: . container_name: astrowind ports: - 8080:8080

后果三：目录已更名

src/content/post在 Astro 5 迁移中已不存在，统一使用src/data/post。任何沿用旧目录的教程、脚本或 CI 配置都会失效，新增文章时必须写入新路径。

发布新文章的四种可行方案

方案一与方案二都建立在"构建期读取"之上，本质是"内容变了就重新构建"；方案四是唯一能脱离本地文件目录的路径，需要自行实现符合 Astro Content Layer 规范的加载器，仓库内未内置，属于自定义开发范畴。

实战示例：在 Docker 中重建并发布文章

docker build -t my-site . # 镜像构建过程中会执行 npm run build docker run -p 8080:8080 my-site

新增一篇文章 = 提交文件 + 重新docker build。流程为：

1. 在src/data/post/下新建.md或.mdx文件，并填写 frontmatter（字段要求见仓库技能文档 .agents/skills/add-blog-post.md：title必填，publishDate、draft、excerpt、image、category、tags、author、metadata均可选）；
2. 提交到 Git（或直接保留在构建上下文目录中）；
3. 重新执行docker build -t my-site .，让 build 阶段把新文章编译进dist/；
4. 重启容器docker run -p 8080:8080 my-site。

文章 URL 由 src/config.yaml 中apps.blog.post.permalink决定，默认值为/%slug%，slug 由文件名派生；也支持%year%/%month%、%category%、%day%等变量组合，具体解析逻辑见 src/utils/permalinks.ts。

深入源码：fetchPosts()缓存、草稿过滤与静态路由

全构建期的结果缓存

文档指出getCollection('post')被 src/utils/blog.ts 的fetchPosts()包装，且结果会在整个构建期内缓存。源码印证如下：

let _posts: Array<Post>; export const fetchPosts = async (): Promise<Array<Post>> => { if (!_posts) { _posts = await load(); } return _posts; };

_posts是模块级变量，首次调用fetchPosts()时执行load()完成读取与归一化，之后所有页面、路由、组件共享同一份结果。load()内部通过getCollection('post')获取原始条目，再经getNormalizedPost()处理——包括用cleanSlug()清洗 slug、按POST_PERMALINK_PATTERN生成永久链接、通过render(post)渲染正文并提取readingTime等。

基于此缓存的派生查询还包括：

• findPostsBySlugs()/findPostsByIds()：按 slug 或 id 检索；
• findLatestPosts({ count })：默认取最新 4 篇；
• getRelatedPosts()：按分类（+5 分）与标签（+1 分）相似度打分排序的关联文章推荐。

草稿过滤发生在load()阶段

文档提到draft: true的文章会在fetchPosts()中被过滤。对应实现位于load()的管道尾部：

const results = (await Promise.all(normalizedPosts)) .sort((a, b) => b.publishDate.valueOf() - a.publishDate.valueOf()) .filter((post) => !post.draft);

即先按publishDate降序排列，再过滤掉草稿。草稿文章不会出现在博客列表、分类页、标签页、RSS 与 sitemap 中。博客列表的分页大小由apps.blog.postsPerPage控制（仓库配置为 8），用于getStaticPathsBlogList()等静态路由的生成。

全站路由均为构建期静态生成

博客相关路由全部通过getStaticPaths*系列函数在构建期生成（见 src/utils/blog.ts 与 src/pages/[...blog] 目录）：

• getStaticPathsBlogList()：博客列表页（含分页）；
• getStaticPathsBlogPost()：每篇文章详情页；
• getStaticPathsBlogCategory()/getStaticPathsBlogTag()：分类页与标签页（均支持分页）。

这些路由在构建时一次性枚举内容集合的全部条目，进一步印证"内容只存在于构建期"的结论。

关于 SSR 的现状与展望

AstroWind v1 是静态模板，不支持 SSR（按需渲染）。文档明确说明 SSR 支持计划在 AstroWind v2 中提供。因此，如果当前需要在运行期动态提供内容，有两个可行的替代路径：

1. 使用重建触发机制：通过 CI / 部署钩子 / webhook 在内容变更时重新构建（最直接，也最贴合本仓库现状）；
2. 实现自定义构建期加载器：将glob()替换为从 CMS 或 API 拉取内容的加载器，在每次构建时同步远端内容。

总结

AstroWind 采用"内容在构建期读取并烘焙"的架构：内容集合由glob()加载器在src/data/post中编译，产出静态dist/，再由 nginx 静态托管（Dockerfile 即此模型的参考实现）。因此，发布文章的稳定路径是"变更内容 → 重新构建"，无论是 Git 提交触发 CI 重建、手动执行npm run build、重建 Docker 镜像，还是替换为远端内容加载器。fetchPosts()的模块级缓存与草稿过滤进一步明确了内容读取的时机与边界。对需要在运行期提供动态内容的场景，可关注 AstroWind v2 的 SSR 支持。

• 前端
• UI组件