从零搭建一个免费的 Astro 个人主页，并部署到 Cloudflare Pages

最终结果

站点已经发布到 Cloudflare Pages，项目名是maris-homepage-20260630，免费访问地址是：

https://maris-homepage-20260630.pages.dev/

这次做出来的是一个单页个人主页，包含首屏介绍、作品、文章、时间线和联系区。

技术选型

我选择的是这一套：

• Astro：适合静态个人主页和博客，构建快，部署简单。
• Tailwind CSS：快速写响应式样式，不需要额外维护很多 CSS 文件。
• Cloudflare Pages：免费托管静态站点，发布后自动获得 pages.dev 域名。
• Wrangler：Cloudflare 官方命令行工具，用来登录、创建 Pages 项目和部署。

本地项目结构

项目放在：

D:\Users\maris\Documents\EasyBlog

关键文件如下：

• src/pages/index.astro：首页页面内容。
• src/styles/global.css：全局样式、颜色、页面宽度等。
• src/assets/hero-art.png：首屏视觉图。
• public/favicon.svg：站点图标。
• public/images/：文章中使用的截图。
• README.md：项目说明和重新部署命令。

创建 Astro + Tailwind 项目

这个仓库一开始只有 .git，所以我直接手动创建了 Astro 项目文件，而不是用模板覆盖。 核心依赖写在 package.json：

{
  "name": "easyblog",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
  "dependencies": {
    "@tailwindcss/vite": "^4.1.13",
    "astro": "^7.0.3",
    "tailwindcss": "^4.1.13"
  }
}

Astro 配置文件 astro.config.mjs 接入 Tailwind 的 Vite 插件：

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

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

安装依赖：

npm install

设计首页

首页内容集中在 src/pages/index.astro，顶部用一个 profile 对象管理常改信息：

const profile = {
  name: "你的名字",
  role: "独立创作者 / 开发者",
  location: "Shanghai",
  email: "hello@example.com",
  intro:
    "我把复杂想法整理成清晰的文字、产品和界面。这里收藏我的项目、文章与最近正在探索的方向。",
};

后续如果要改名字、职业、邮箱和简介，优先改这里。

视觉上采用了浅色纸感背景、黑色大标题、少量青绿色和珊瑚色点缀。首屏右侧使用生成的抽象视觉图， 让页面不像纯文字模板。

本地运行和构建

本地预览命令：

npm run dev -- --host 127.0.0.1 --port 4321

浏览器打开：

http://127.0.0.1:4321/

构建静态产物：

npm run build

构建成功后，Astro 会生成 dist/ 目录，Cloudflare Pages 部署的就是这个目录。

安全审计和依赖升级

第一次安装后运行了：

npm audit --omit=dev

当时 npm 提示 Astro 旧版本链上有安全公告，所以我把 Astro、Tailwind 和 Tailwind Vite 插件升级到最新版本：

npm install astro@latest tailwindcss@latest @tailwindcss/vite@latest

升级后重新运行审计，结果为：

found 0 vulnerabilities

截图检查

页面做完后，我分别检查了桌面和窄屏效果，发现过一次按钮文字颜色被全局链接样式覆盖的问题， 也顺手调整了手机端标题换行和页面宽度写法。

Git 提交

在本地把分支切到 main，并提交初始版本：

git branch -M main
git add .
git commit -m "Build personal homepage"

后面又提交了一次部署文档：

git add README.md
git commit -m "Document Cloudflare Pages deployment"

Cloudflare Pages 页面操作

如果用网页控制台手动配置，大致步骤是：

1. 打开 Cloudflare Dashboard。
2. 进入左侧 Workers & Pages。
3. 选择 Pages。
4. 点击创建项目。
5. 如果连接 GitHub，就选择仓库并授权 Cloudflare 读取仓库。
6. 框架预设选择 Astro。
7. Build command 填 npm run build。
8. Build output directory 填 dist。
9. 生产分支选择 main。
10. 点击保存并部署。

这次因为本机没有 GitHub CLI，所以我没有先走 GitHub 自动部署，而是用 Wrangler 直接把dist 发布到 Cloudflare Pages。后续仍然可以在 Cloudflare 页面里再连接 GitHub 仓库。

Wrangler 登录

先确认 Wrangler 可用：

npx wrangler --version

输出版本是：

4.105.0

登录 Cloudflare：

npx wrangler login

这个命令会打开 Cloudflare OAuth 授权页面。页面里登录账号后点击授权，终端会显示Successfully logged in.。

Wrangler 还询问是否自动安装 Cloudflare skills，这和本次部署无关，所以选择了 no， 保持项目干净。

创建 Pages 项目

第一次直接部署时，Wrangler 交互式创建项目遇到 Cloudflare API 的临时 500 错误。

解决方式是先明确创建项目，再部署：

npx wrangler pages project create maris-homepage-20260630 --production-branch main

成功输出类似这样：

Successfully created the 'maris-homepage-20260630' project.
It will be available at https://maris-homepage-20260630.pages.dev/ once you create your first deployment.

部署到 Cloudflare Pages

先构建：

npm run build

再部署：

npx wrangler pages deploy dist --project-name maris-homepage-20260630 --branch main

成功后终端输出了预览地址：

https://c411addf.maris-homepage-20260630.pages.dev

生产地址是：

https://maris-homepage-20260630.pages.dev/

验证线上可访问

用 PowerShell 请求线上地址：

Invoke-WebRequest -Uri 'https://maris-homepage-20260630.pages.dev/' -UseBasicParsing

验证结果是：

StatusCode : 200
TitleFound : True

这说明 Cloudflare Pages 已经返回页面，并且页面标题匹配。

后续如何更新

修改页面内容后，重复这两条命令即可重新发布：

npm run build
npx wrangler pages deploy dist --project-name maris-homepage-20260630 --branch main

如果之后连接 GitHub 仓库，就可以让 Cloudflare Pages 在每次 push 到 main 后自动构建部署。