从 GitHub Pages 迁移到上码

GitHub Pages 很适合开始。

它的优点大家都知道：

• 接 Git 仓库顺手
• 免费
• 对静态博客和项目页足够友好

但当你的网站开始真正面向国内用户、开始承接正式分享，或者你已经不想每次都围着 GitHub 的发布路径转，迁移就会变成一个很自然的下一步。

什么时候值得迁移

不是所有项目都必须迁。

下面这些情况，通常更值得认真考虑：

1. 访问速度已经影响分享

如果你的网站是发给同学、客户、同事、面试官或中文用户看的，而你自己也经常听到“打不开”“有点慢”“过会儿再看”，那迁移就不是锦上添花了。

2. 你不想每次更新都走 Git 提交流程

GitHub Pages 的默认发布方式，本质上还是围绕代码仓库在转。对博客、作品集和课程项目来说，这当然能用，但对某些“我只想把构建结果发上去”的场景，它不一定是最轻的路径。

3. 你想要更直接的项目能力

比如：

• 项目级访问统计
• 更清晰的部署记录
• 版本回退能力
• 更直接的域名管理

这些能力不一定是 GitHub Pages 的强项。

迁移前，先判断你现在的网站是哪一种

这一步很重要，因为不同站点迁移时要拿的目录不一样。

类型 1：纯静态仓库

比如仓库里本来就直接放着：

• index.html
• style.css
• assets/

这种最简单，拿最终文件目录就能迁。

类型 2：构建型静态站

比如：

• Jekyll
• Hugo
• Hexo
• VuePress / VitePress
• React / Vite 构建后站点

这种不能直接拿源码仓库迁，而是要先构建，再拿构建产物。

迁移的核心原则

迁移这件事说复杂也复杂，说简单也简单。

真正核心只有一句话：

不要迁源码运行方式，要迁最终可访问结果。

也就是说，你要确认的是：

• 现在用户实际访问到的页面是什么
• 它对应的最终构建目录在哪里
• 站点里有没有硬编码 GitHub Pages 相关路径

一套稳妥的迁移顺序

1. 先在本地构建出最终目录

常见例子：

# Jekyll
bundle exec jekyll build

# Hugo
hugo

# Hexo
hexo generate

# VuePress / VitePress / Vite 项目
pnpm build

你最终要拿去迁移的，通常是：

• _site
• public
• dist

而不是整个仓库。

2. 检查这 4 个容易出错的点

资源路径

如果你的网站里还保留着 GitHub Pages 特有的路径假设，比如写死了仓库子路径，迁移后很容易出现资源 404。

自定义域名配置

如果你之前在仓库里放过 CNAME 文件，或者已经做过 GitHub Pages 的域名绑定，迁移后要重新确认域名应该指向哪里。

绝对链接

有些站点在模板里会把链接直接写成旧域名。迁移后如果不检查，页面虽然能打开，分享和 canonical 可能还是旧地址。

404 / 路由行为

如果你的网站有 clean URLs、静态导出后的子路径，迁移后要重点测：

• 根路径
• 典型内页
• 文章页
• 资源页

3. 上传构建产物，先拿临时链接自测

最稳的做法永远不是一上来就切主域名，而是：

1. 先上传最终目录
2. 用临时链接检查页面
3. 确认正常后，再切正式域名

这样你可以把迁移风险压到最小。

如果你用的是上码，这一步更接近“上传静态产物，先拿一个可访问链接”，而不是重新搭一套发布流程。

GitHub Pages 迁过来以后，通常会获得什么

这件事不要理解成“平台对平台”的抽象对比，而是理解成你日常会少踩哪些坑。

1. 发布入口更接近“发结果”

如果你原来的网站每次都是先 build、再 commit、再 push，实际上你真正想发布的是结果目录，而不是“必须通过 GitHub Pages 这条链路”。

2. 更适合国内用户直接访问

这通常是迁移动机里最现实的一条。

3. 域名和 HTTPS 更像项目能力，而不是仓库配置副产物

你不用继续围着 GitHub 仓库、CNAME 文件和 Pages 设置页打转，而是把域名视为网站项目本身的一部分来管理。相关细节可以配合这篇看：静态网站怎么绑定自定义域名？。

4. 版本管理更直接

对持续更新的网站来说，部署记录和回滚能力会比“去 Git 历史里找某次提交再想办法恢复页面”直观得多。

迁移完成后，至少要测这几件事

1. 首页和典型内页

不要只看首页。很多站点首页没问题，文章页或子页面却有路径问题。

2. 图片、CSS、JS 是否全部加载

只要资源路径有一处没改干净，页面就可能在某些路径下残缺。

3. 自定义域名和 HTTPS

如果你要切主域名，这两项必须在切换前后都验证一遍。

4. 老链接是否还需要重定向

如果你之前已经把旧链接发出去过，迁移后要考虑：

• 是否保留原入口一段时间
• 是否做必要重定向
• 是否更新简介、名片页、公众号、README 里的链接

常见问题

迁移后原来的 GitHub Pages 站点还能保留吗？

可以。最稳的做法通常就是先保留原站，等新站临时链接、自定义域名和资源加载都确认无误，再正式切流量。

需要改网站代码吗？

不一定。纯静态站很多时候不需要改代码，真正需要改的是：

• 构建目录选择
• 资源路径
• 域名相关配置

已经绑定自定义域名了，还能迁吗？

当然可以。迁移的关键不在“有没有域名”，而在“什么时候切 DNS”。通常建议先完成新站自测，再切域名解析。

最后的建议

GitHub Pages 很适合开始，但不一定适合所有网站一直停在那里。

如果你的网站已经进入“要稳定给别人看”的阶段，那么迁移时最重要的不是换平台本身，而是把这几件事做对：

• 迁的是最终构建结果
• 先拿临时链接自测
• 再切正式域名
• 切完以后继续检查关键页面和资源

只要顺序对了，迁移本身并没有想象中那么重。