这次部署的目标#

我这次想完成的，不只是把博客挂到一个公网地址，而是把下面这些事情一起做好：

1. 让项目本地可以稳定构建
2. 让 GitHub Actions 和真实生产构建保持一致
3. 把仓库接入 EdgeOne Pages 自动部署
4. 确保文章页、静态资源、搜索和基础品牌元素都能正常工作
5. 给后续继续更新博客留下一套清晰的上线流程

如果只盯着“能不能打开首页”，往往会在后面反复返工。对个人博客来说，部署真正有用的状态应该是：它不仅能打开，而且以后每次改动都能顺利发布。

先说一下我的项目情况#

我的站点是一个静态输出的 Astro 项目，核心情况大概如下：

• 仓库托管在 GitHub
• 主分支使用 main
• 包管理器使用 pnpm
• 构建输出目录是 dist
• 实际上线使用的命令是 pnpm build

需要特别说明的是，这个项目的 build 不是最基础的 astro build，而是带了完整前后处理流程：

1
"build": "node scripts/update-anime.mjs && astro build && pagefind --site dist && node scripts/compress-fonts.js"

这意味着部署平台上的构建命令必须和项目真实构建流程保持一致，不能想当然地写成 astro build。只要这一点配错，后面你看到的很多报错都只是结果，不是根因。

为什么我最后选择了 EdgeOne Pages#

一开始我其实也看过其他常见的静态站点部署方式，但最后还是决定试试 EdgeOne Pages。原因很直接：

• 接 GitHub 仓库比较顺
• 对静态博客足够友好
• 配自定义域名相对省心
• 更适合我这种不想额外维护服务端的个人站点场景

对博客来说，最理想的部署方式不是最复杂的，而是“改完代码推上去，它就能自动构建和发布”。从这个角度看，EdgeOne Pages 确实是一个比较轻量也比较合适的选择。

第一步：先把本地构建链路摸清楚#

真正开始部署之前，我和 AI 先做的第一件事，不是去点平台控制台，而是把项目本身先看明白。

重点检查的内容包括：

• 有没有 package.json
• 有没有 pnpm-lock.yaml
• astro.config.mjs 是否为 output: "static"
• 实际构建命令是不是 pnpm build
• 输出目录是不是 dist

确认下来之后，部署平台的核心参数也就跟着明确了：

1
安装命令：pnpm install
2
构建命令：pnpm build
3
输出目录：dist

另外，这个项目还有一段构建前脚本：

1
"prebuild": "node scripts/sync-content.js || true"

而 scripts/sync-content.js 默认会尝试执行内容同步逻辑。为了让远程构建环境更稳，我最终在部署环境里显式设置了：

1
ENABLE_CONTENT_SYNC=false

这一步非常关键。因为本地环境“刚好能跑”，并不代表远程环境也会自然照着你的预期运行。凡是依赖环境变量、外部仓库、额外接口或本地状态的脚本，都应该提前想清楚。

第二步：先把 GitHub Actions 整理干净#

这次部署里我遇到的第一个明显问题，其实不在 EdgeOne，而在自己的 GitHub Actions。

之前工作流里有几个典型的不一致：

• 有的 workflow 监听 master
• 有的 workflow 监听 main
• 有的跑的是 pnpm astro build
• 有的才是我真正上线会用的 pnpm build

这会导致一个很麻烦的结果：你根本分不清是平台有问题，还是你自己的 CI 和生产构建本来就不是一套逻辑。

所以我先做了下面几件事：

1. 把 master/main 混用统一为 main
2. 删除重复或用途重叠的 workflow
3. 把主构建流程统一到 pnpm build
4. 把不再需要自动运行的部署 workflow 改成手动触发，减少无意义红叉

整理完之后，GitHub 那边真正需要关注的就只剩下构建和检查本身，而不是一堆相互打架的旧流程。

第三步：我踩到的第一个真坑，是 Astro Check 报错#

在真正接入 EdgeOne Pages 之前，Astro Check 就先暴露了问题。

报错点落在公告组件的内联脚本上。本质原因是：

• Announcement.astro 里的 <script define:vars=...> 会被当成浏览器内联脚本
• 这类脚本不会按 TypeScript 文件处理
• 但脚本里用了 (widget as HTMLElement) 这种 TS 断言

于是检查直接报错：

1
Type assertion expressions can only be used in TypeScript files.

最后修法其实很清晰：

1. 显式加上 is:inline
2. 把类型断言改成普通浏览器 JS 判断

例如：

1
if (widget instanceof HTMLElement) {
2
  widget.style.display = "none";
3
}

这个坑看上去像一个“小语法问题”，但它影响的是整条 CI 链路。只要 CI 没绿，你后面在部署平台上看到的很多失败，本质上都只是前置问题没有先清掉。

第四步：把仓库接进 EdgeOne Pages#

等本地构建逻辑和 GitHub Actions 都整理得差不多之后，我才正式去 EdgeOne Pages 控制台创建项目。

实际操作流程并不复杂：

1. 新建项目
2. 选择导入 Git 仓库
3. 授权 GitHub
4. 选择目标仓库
5. 把生产分支指定为 main

如果平台能自动识别 Astro 当然最好；如果没有识别完整，就手动填。

我最后使用的参数大致如下：

1
Root Directory: ./
2
Install Command: pnpm install
3
Build Command: pnpm build
4
Output Directory: dist

不过为了减少 pnpm 版本差异带来的问题，更稳一点的写法其实是：

1
corepack enable && corepack prepare pnpm@10.33.0 --activate && pnpm install --frozen-lockfile

因为我的项目里已经明确写了：

1
"packageManager": "pnpm@10.33.0"

部署平台不一定原生就带这个版本，提前对齐会更省事。

第五步：环境变量一定要补齐#

很多首次部署失败，不是因为平台不会构建，而是因为平台不知道你项目默认依赖了什么。

我这次至少补了：

1
ENABLE_CONTENT_SYNC=false

如果你的项目后面还接了其他内容同步、第三方 API、私有数据源或自动生成脚本，也应该在这里一并确认。

我的经验是：部署平台不会“理解你的本地习惯”，它只会按你明确提供的命令和环境去执行。所以任何隐含约定，最好都显式写出来。

第六步：首次构建成功后，不要立刻松懈#

第一次看到部署成功，当然会松一口气，但事情其实还没有结束。

我后来没有马上宣布收工，而是先逐项检查预览站点：

• 首页能不能正常打开
• 文章页是不是都能进入
• 静态资源有没有 404
• 搜索和页面切换有没有异常
• favicon、标题、GitHub 链接这些个性化配置有没有生效

这一步非常有必要，因为“构建成功”只说明产物生成出来了，不代表访问体验已经完全正常。

第七步：我后面实际补做了哪些站点收口#

部署成功之后，我并没有立刻停下来，而是顺手把站点继续收口成更像自己的样子。

后面我陆续做了这些事情：

• 把站点标题改成 WYZの拾忆录
• 统一 GitHub 地址到自己的账号
• 调整 favicon，让小尺寸下更清晰
• 整理文章结构和命名
• 把原本分散的示例文章合并成一篇 Muzuki使用指南
• 给特定文章加上密码保护

这些动作表面上是在“改站点细节”，本质上其实也属于部署的一部分。因为真正的上线，不只是把模板放到网上，而是让这个站点开始拥有清晰的内容结构和自己的风格。

第八步：我还踩到了一个很隐蔽的 404#

后面还有一个很典型的坑，不在文章内容本身，而在页面切换缓存。

当新文章刚上线时，首页列表已经能看到卡片，但点击以后却还是进了 404。最开始很容易怀疑是：

• 文章没生成
• 路由写错了
• 链接拼错了

但真正排查下来发现，构建产物里其实已经存在这篇文章页面，问题更像是前端切换层把旧的 404 结果缓存住了。站点使用了 swup 做页面过渡，而它默认会保留内存缓存；如果某个地址在文章真正可访问之前被点开过，后面即使页面已经上线，也可能还沿用旧的 404 结果。

最后的修法是两部分一起处理：

1. 先把站内所有文章链接统一成真实 URL 生成逻辑
2. 在 404 页面出现时清掉 swup 缓存，避免旧 404 一直复用

这个问题很有代表性，因为它提醒我一件事：当你看到“首页有文章，但点进去 404”时，不一定是 Markdown 文件错了，也可能是运行时缓存和页面切换逻辑在捣乱。

这次和 AI 一起做这件事，最大的价值是什么#

以前我对 AI 的预期比较朴素，更多是：

• 帮我改几句文案
• 帮我看看报错
• 顺手给我几条命令

但这次更像是一种真正意义上的“结对部署”。

我把目标告诉 AI 之后，它不是只给我一个抽象的原理解释，而是先进入当前仓库，帮我一起确认：

• 现在项目到底怎么构建
• 工作流为什么会红
• 哪些问题是表象，哪些才是根因
• 哪些改动应该在本地做，哪些该去平台里调

这种协作方式和单纯看教程最大的区别在于：

• 教程告诉你“通常应该怎么做”
• 对话协作会告诉你“你这个仓库现在应该怎么做”

而部署这种事情，最怕的就是只懂通用流程，却不知道当前项目卡在哪一层。

我最后沉淀下来的部署顺序#

如果以后我要再部署一次类似博客，我会优先按这个顺序来：

1. 本地先确认 pnpm build 能过
2. 搞清楚输出目录是不是 dist
3. 把 GitHub Actions 统一到真实生产流程
4. 补齐部署环境变量
5. 再把仓库接入 EdgeOne Pages
6. 构建成功后先检查预览地址
7. 再处理域名、HTTPS 和品牌细节
8. 最后顺手排查缓存、路由和前端切换层问题

顺序一旦理顺，后面的部署会轻松很多。

最后的感受#

这次把博客部署到 EdgeOne Pages，并不是那种一键完成的“爽文流程”。中间有 CI 报错、工作流混乱、favicon 不清晰、文章路由 404、前端缓存干扰这些零碎问题。

但也正因为这些问题都被一个个拆开解决掉，最后这个站点才真正变成了“我的站点”，而不是“我把一个模板传到了网上”。

如果你也正在把自己的博客部署到 EdgeOne Pages，我更推荐你这样做：

• 不要一上来就急着点部署
• 先把项目真实构建流程摸清楚
• 先让本地和 CI 保持一致
• 再把部署平台当成最后一环

这样会少走很多弯路。

而如果你愿意和 AI 一起做这件事，它最好的角色不是替你点按钮，而是帮你把分散的信息、零碎的报错和杂乱的配置，慢慢收束成一条真正能落地的路径。