操作附录：在Windows 11上用Astro、GitHub和Cloudflare Pages发布网站

本文记录《跟着ChatGPT学AI》网站从本地开发到公网发布的基本操作流程。

适用对象是没有现代网站开发经验，但希望借助AI完成个人知识网站的人。

一、准备开发环境

需要安装四项工具：

Node.js；
Git；
VS Code；
Codex。

建议使用Node.js长期支持版。安装后，在PowerShell中检查：

node -v
npm -v
git --version

能够正常显示版本号，说明基础环境已经安装成功。

如果PowerShell阻止运行npm脚本，可执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

按提示确认后，关闭并重新打开终端。

二、建立项目目录

本项目使用的目录是：

D:\AI-Projects\genzhe-chatgpt-xue-ai

在VS Code中打开该目录，并确认终端当前路径正确。

cd D:\AI-Projects\genzhe-chatgpt-xue-ai

项目名称最好使用小写英文和连字符，避免空格、中文路径和特殊符号带来的兼容问题。

三、创建Astro项目

可以使用Astro官方初始化命令：

npm create astro@latest

根据提示选择：

使用基础模板；
使用TypeScript；
安装依赖；
初始化Git仓库。

项目创建完成后，启动本地开发服务器：

npm run dev

终端会显示本地地址，通常类似：

http://localhost:4321

在浏览器中打开，确认网站能够正常运行。

四、建立内容结构

本项目设置四类内容：

src/content/courses
src/content/reviews
src/content/practices
src/content/electromagnetic-ai

分别用于：

AI学习课程；
章节复习；
AI实践；
AI与电磁工业软件专题。

文章使用Markdown编写，基础信息放在frontmatter中，例如：

---
title: "文章标题"
description: "文章摘要"
publishedDate: 2026-08-06
order: 1
draft: false
---

课程内容还增加：

chapter: 1
lesson: 1

本项目规定：

lesson: 0    导读
lesson: 1–98 正式课程
lesson: 99   章末总结

这样可以统一处理课程排序、统计和前后篇导航。

五、建立页面和布局

网站主要包括：

/
 /courses/
 /reviews/
 /practices/
 /electromagnetic-ai/

页面布局分为两类：

BaseLayout：负责全站导航、页脚和基础元信息；
ArticleLayout：负责文章标题、正文、目录和导航。

内容列表页读取对应内容集合，文章页通过动态路由自动生成。

完成基础页面后，执行：

npm run build

只有构建成功，才能说明页面路由、内容格式和代码结构基本正确。

六、使用Git保存稳定版本

先检查状态：

git status

查看修改范围：

git diff --stat
git diff --check

确认无误后提交：

git add .
git commit -m "feat: describe this change"

常用提交类型包括：

feat: 新增功能
fix: 修复问题
docs: 修改文档
style: 调整样式
chore: 工程或辅助修改

每完成一个稳定阶段就提交一次，不要积累大量未经验证的修改。

查看最近提交：

git log --oneline -5

七、创建GitHub仓库

注册GitHub账号后，新建一个空仓库。

仓库名称：

genzhe-chatgpt-xue-ai

创建时不要勾选：

README；
.gitignore；
License。

因为本地项目已经包含这些内容。

仓库创建后，复制HTTPS地址，例如：

https://github.com/用户名/genzhe-chatgpt-xue-ai.git

在本地项目终端执行：

git remote add origin https://github.com/用户名/genzhe-chatgpt-xue-ai.git
git remote -v

第一次推送：

git push -u origin main

完成浏览器授权后，GitHub仓库中应出现全部代码和提交历史。

以后通常只需执行：

git push

八、连接Cloudflare Pages

进入Cloudflare控制台，选择：

Workers & Pages
→ Create
→ Pages
→ Connect to Git

不要误选Workers部署流程。

授权Cloudflare访问GitHub仓库后，选择：

genzhe-chatgpt-xue-ai

构建配置填写：

Production branch: main
Framework preset: Astro
Build command: npm run build
Build output directory: dist
Root directory: 留空

增加环境变量：

SITE_URL=https://genzhe-chatgpt-xue-ai.pages.dev

然后点击保存并部署。

部署成功后，网站即可通过默认地址访问：

https://genzhe-chatgpt-xue-ai.pages.dev

九、配置上线基础能力

正式发布前，至少应具备：

页面标题；
description；
canonical；
Open Graph；
favicon；
404页面；
robots.txt；
sitemap；
草稿过滤；
死链接检查。

Astro配置中设置站点地址：

const site =
  process.env.SITE_URL?.trim() ||
  'https://example.invalid/';

正式部署时必须配置SITE_URL，否则canonical和sitemap会使用临时回退地址。

Sitemap可使用Astro官方集成：

npm install @astrojs/sitemap

并在配置文件中启用：

integrations: [sitemap()]

十、检查公网网站

首次部署后，至少检查：

/
 /courses/
 /reviews/
 /electromagnetic-ai/
 /robots.txt
 /sitemap-index.xml
 /favicon.svg
 /一个不存在的地址

还应查看页面源代码中的canonical，例如：

<link
  rel="canonical"
  href="https://genzhe-chatgpt-xue-ai.pages.dev/"
/>

不存在的地址应显示自定义404页面。

十一、完成自动部署闭环

本地修改完成后：

git status
git add .
git commit -m "fix: update website"
git push

GitHub收到新提交后，Cloudflare Pages会自动执行：

拉取代码
→ 安装依赖
→ npm run build
→ 发布dist目录

部署成功后，公网网站自动更新。

这形成了稳定工作流：

本地修改
→ 构建检查
→ Git提交
→ 推送GitHub
→ Cloudflare自动发布
→ 公网验收

十二、响应式测试

不要只测试电脑和一个手机模拟尺寸。

本项目最终采用：

默认：手机单栏
宽度≥680px且高度≥600px：平板双栏
宽度≥1050px且高度≥500px：桌面布局

最低建议测试：

同时在真实设备上检查：

普通手机；
手机横屏；
折叠手机折叠状态；
折叠手机展开状态；
平板竖屏；
平板横屏；
电脑浏览器。

模拟器通过，不代表真实设备一定通过。

十三、常用命令

启动本地网站：

npm run dev

正式构建：

npm run build

检查Git状态：

git status

检查格式问题：

git diff --check

提交修改：

git add .
git commit -m "提交说明"

推送远程仓库：

git push

查看最近提交：

git log --oneline -5

检查远程仓库：

git remote -v

十四、操作原则

整个过程中，最重要的不是记住所有命令，而是保持固定节奏：

一次只做一项修改
→ 本地检查
→ 构建验证
→ 人工验收
→ Git提交
→ 推送部署

不要把多个未经验证的任务混在一次提交中。

AI可以生成代码和命令，但每一步是否正确，仍需要人检查页面、终端输出和真实设备效果。

下一篇配套文档将集中整理本项目遇到的真实问题，包括PowerShell权限、Git配置、内容结构、响应式断点、旧版浏览器和Cloudflare缓存。