用Codex和GitHub Actions实现个人网站的自动化部署

花了一下午，让 Codex 帮你搭好了一个个人网站。本地预览一切正常，配色、排版、文案都满意。然后你把链接发给朋友——对方回了一句：打不开。

这不是个例。很多刚接触 AI 编程工具的开发者，第一次用 Codex 写完整项目后，都会卡在同一个环节：代码在本地能跑，却不知道怎么把网站真正“放”到公网让别人访问。更麻烦的是，后面每改一次文案、每加一个作品，都要重新构建、重新上传，发布变成了一项重复却不得不做的体力活。

这篇文章想解决的，就是这两个问题：第一，怎么用一个可靠、免费、带 HTTPS 的静态网站托管方案；第二，怎么把“改代码 → 自动发布”这条链路做成一条流水线，让迭代不再依赖手动操作。

先说结论：Codex 负责生产代码，GitHub 负责托管代码，GitHub Actions 负责自动构建，GitHub Pages 负责对外提供访问入口。四者组合起来，就是一个完整的、几乎零成本的个人网站发布工作流。

1. 这篇文章真正要解决的问题

1.1 别人为什么访问不了你的网站

先说第一个痛点：“网站开发完了，别人却访问不了”。

绝大多数情况下，原因非常简单：你只是在本地启动了开发服务器。Codex 也好，其他 AI 编程工具也好，默认启动的开发服务器是以localhost或127.0.0.1为地址的。这个地址的意思是“只有这台电脑自己能访问”，别人的浏览器请求根本到不了你的机器。

有些开发者会尝试把地址改成局域网 IP，比如192.168.x.x，然后发给同事。这个方案在同一个 WiFi 下能临时用，但一旦对方不在同一个网络环境，请求依然会被路由器或防火墙挡在外面。更不用说动态 IP、运营商 NAT、电脑休眠这些变数，都会让这个方案彻底失效。

所以，“别人打不开”不是 Codex 的问题，而是部署方式的问题。你缺的不是“更聪明的 AI”，而是一个真正公网可达的托管出口。

1.2 为什么每次迭代都像在上传文件

第二个痛点是“每次迭代都要手动上传”。

很多人第一次发布网站，用的是最朴素的方式：把 HTML 文件打包，打开服务器面板，找到文件管理，上传，覆盖。或者用 FTP 工具连接服务器，把本地文件拖上去。这个流程第一次用还能接受，第二次、第三次就会非常痛苦。

如果只改了一个标题、换了一张图片，你也必须走一遍完整的“打包 → 连接 → 上传 → 覆盖”流程。一旦操作顺序错了，比如先覆盖了旧文件再上传新文件，中间还会出现一小段时间线上页面是坏的。

更隐蔽的问题是，手动上传没有“版本”概念。你改坏了，想找回昨天的版本，如果本地没有备份，就只能靠服务器上那个被覆盖掉的文件了。

1.3 这个问题该怎么解

正确解法不是找一台更稳定的服务器，而是把发布流程工程化。

简单说，就是用 Git 管理代码，用 GitHub 托管仓库，用 GitHub Actions 做自动构建，用 GitHub Pages 做静态托管。Codex 在其中负责最前面那一步：写代码、改代码。

这套链路的好处是：

• 发布不再依赖人记性好，push 到仓库就自动上线；
• 每一次修改都有提交记录，改坏了可以随时回滚；
• 托管和构建都不需要单独付费，适合个人网站场景。

这篇文章后面的内容，就是围绕这条链路一步步展开的。

2. Codex 是什么，GitHub Pages 又是什么

2.1 Codex 不是普通代码补全工具

Codex 是 OpenAI 推出的 AI 编程代理工具。它和常见的“代码补全插件”有一个本质区别：补全插件是在你写代码时给出建议，而 Codex 是可以在终端里直接执行任务的代理。

你给它一个任务，比如“创建一个人网站首页，包含 Hero 区域和作品展示区域”，它会自己做决策：读取项目结构、创建文件、安装依赖、启动开发服务器、修改代码、执行测试。它可以连续执行多个步骤，而不是只等你打完一行再给一个补全建议。

不过要注意，Codex 的能力边界是“生成和修改代码”。它不负责把网站发布到公网，也不负责注册域名、配置服务器。很多人用 Codex 开发完网站后以为万事大吉，实际上是忽略了部署这个环节。

Codex 的使用形态也有多种：命令行 CLI、桌面端、IDE 插件等。不同版本的命令细节可能不太一样，建议先以官方文档为准。本文的核心流程不依赖 Codex 的某个特定版本，只要你能在终端里以某种方式启动 Codex 并让它读写项目目录即可。

2.2 GitHub Pages 是免费静态托管方案

GitHub Pages 是 GitHub 提供的静态网站托管服务。它可以直接托管 HTML、CSS、JavaScript 文件，支持 HTTPS，也支持绑定自定义域名。

它适合什么场景？个人网站、作品集、项目文档、小型博客、单页应用。它不适合什么场景？需要服务端计算、数据库、用户登录、动态接口的网站。

很多人觉得 Pages 很简陋，但换个角度想：一个个人主页网站，主要展示个人信息、作品、博客文章，这些内容大部分是静态的。你完全没必要为了一个纯静态网站去买一台服务器、装 nginx、配 HTTPS 证书。Pages 把这些事情全部包掉了。

Pages 最常见的使用方式是配合公共仓库，这样做的好处是托管不需要额外费用。如果仓库是私有的，则要看 GitHub 当前套餐对 Pages 的支持情况。对个人网站来说，公共仓库通常没有压力，因为网站源代码本身就是你愿意公开的内容。

2.3 为什么这套组合能解决“手动上传”问题

如果用一句话概括：Codex 负责“生产代码”，GitHub 负责“保管代码”，GitHub Actions 负责“自动构建”，Pages 负责“对外发布”。

这个组合把发布从“手动工序”变成了“自动流水线”。你每次改完代码，只要 push 到 GitHub 仓库，后续的构建、发布环节都由 GitHub 自动完成。这样做至少有三层收益：更快的发布速度、更可靠的回滚能力、更低的维护成本。

3. 环境准备与前置条件

在开始操作之前，建议先确认本机环境。

3.1 需要准备什么

• 一台能联网的电脑，Windows、macOS 或 Linux 均可；
• 一个 GitHub 账号；
• Git 客户端，并配置好全局用户名和邮箱；
• Node.js 环境，用于本地预览和构建前端项目；
• 一个编辑器，推荐 VSCode，方便查看 Codex 生成的文件；
• Codex 工具本身，并完成登录认证。

3.2 安装并确认 Codex 可用

Codex 的安装方式以官方文档为准。常规情况下，CLI 形态可以通过官方安装包或包管理器安装。安装完成后，在终端输入：

codex --version

如果能输出版本号，说明安装成功。接下来需要完成登录。具体命令可能因版本而异，用官方引导流程完成即可。登录成功的标志是，你可以直接发起一个最简单的对话任务，比如让 Codex 解释当前目录里的一个文件。

这里有一个建议：第一次使用 Codex 时，先在一个空目录里跑一个小任务，确认它能正常工作，再开始做正式项目。否则，当 Codex 在大型项目里表现异常时，你很难判断是模型问题、网络问题还是环境问题。

3.3 创建一个 GitHub 仓库

登录 GitHub，点击右上角的“+”号，选择“New repository”。仓库名建议使用小写字母和连字符，比如my-personal-site。可见性选择 Public，这样 Pages 托管可以免费使用。

先不要勾选“Add a README file”等初始化选项，保持空仓库。这样后面从本地推送时最干净，不容易出现冲突。

4. 整体架构与工作流设计

4.1 传统发布方式与新工作流对比

先看传统方式：

1. 本地写代码；
2. 手动执行构建命令；
3. 打开服务器面板或 FTP 工具；
4. 上传文件到服务器指定目录；
5. 手动下载日志排查问题；
6. 如果需要回滚，手动把备份文件重新上传。

这套流程最大的问题，不是每一步有多难，而是每一步都需要人记得执行、执行正确、按顺序执行。只要有一次遗漏，线上就可能出问题。

再看新方式：

1. 用 Codex 写代码或改代码；
2. 本地预览确认没有问题；
3. 执行 git add、git commit、git push；
4. GitHub Actions 自动构建；
5. GitHub Pages 自动更新线上网站；
6. 如果需要回滚，git revert 后再次 push。

对比之后可以看到，新方式真正解放的不是“写代码”这一步，而是“发布”这一步。发布变成了 Git 提交的副产品，只要提交没问题，上线就自动完成。

4.2 部署链路的完整流程

这条链路可以拆成几个环节：

• 本地开发环境：Codex 读取项目，修改源码；
• 版本控制：Git 记录每一次变更；
• 远程仓库：GitHub 保存代码，并对外提供访问；
• 持续集成：GitHub Actions 监听 push 事件，执行构建；
• 静态托管：GitHub Pages 把构建产物发布为公网网站。

如果你完全不懂 CI/CD，也不用担心。GitHub Actions 的工作流文件就是一个 YAML 文件，它描述“当 main 分支有新提交时，执行哪些步骤”。把它当作一个自动化脚本即可。

4.3 Codex 在这个流程中的边界

有一个观点必须说清楚：Codex 不会替你解决部署问题，但它可以帮你执行部署命令。

你可以让 Codex 完成 Git 提交和推送操作，也可以让它帮你创建 GitHub Actions 的配置文件。但你需要自己理解部署链路，否则配置一旦出错，面对一堆 YAML 报错日志时，你依然会卡住。

我的建议是：第一次搭建时，手动完成 Git 推送和 Pages 配置；跑通之后再尝试让 Codex 协助处理重复性操作。这样你对整条链路有掌控力，而不是把一切都丢给 AI。

5. 用 Codex 从零创建个人网站的完整实操

5.1 建立项目目录并启动 Codex

假设我们要创建一个个人网站，包含首页、关于我、作品展示三个板块。先建立项目目录，并启动 Codex。

mkdir my-personal-site cd my-personal-site codex

在 Codex 交互模式下，给它一个清晰的任务描述：

请帮我创建一个个人网站项目： 1. 使用原生 HTML、CSS、JavaScript，不引入框架； 2. 包含三个页面：首页（index.html）、关于我（about.html）、作品集（works.html）； 3. 有一个公共样式文件 style.css 和一个公共脚本文件 main.js； 4. 页面顶部有导航栏，底部有页脚； 5. 网站风格简洁现代，以我个人的技术作品展示为主要目的。

这里的关键是明确告诉 Codex：技术栈是什么、输出哪些文件、整体结构是什么。任务描述越具体，生成结果越接近你想要的效果。如果只写“帮我做个网站”，Codex 可能给你一个单页示例，结构未必符合预期。

5.2 本地预览和验证

生成完成后，先用浏览器打开index.html，确认页面能正常显示。如果项目引入了前端构建工具，那么先安装依赖并启动开发服务器：

npm install npm run dev

这里要提醒一点：如果 Codex 生成的项目需要构建步骤，请一定要先在本地确认构建命令可以通过。最常见的做法是执行：

npm run build

确认dist目录或者项目根目录下能生成最终的 HTML/CSS/JS 文件。这一步能不能通过，直接决定后面 push 到 GitHub 后，GitHub Actions 会不会构建失败。

5.3 一个典型的静态站点结构

Codex 生成的内容会因模型和任务描述不同而不同，但典型的个人静态网站结构大致如下：

my-personal-site/ ├── index.html ├── about.html ├── works.html ├── css/ │ └── style.css ├── js/ │ └── main.js └── assets/ └── images/

下面给出一个最简单的index.html示例。注意，这里展示的是静态站的基础形态，实际以 Codex 输出为准：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>我的个人网站</title> <link rel="stylesheet" href="css/style.css" /> </head> <body> <nav> <a href="index.html">首页</a> <a href="about.html">关于我</a> <a href="works.html">作品集</a> </nav> <header> <h1>你好，我是前端开发者</h1> <p>这里展示我的技术作品与个人介绍。</p> </header> <script src="js/main.js"></script> </body> </html>

这个页面的关键点在于所有资源都使用相对路径。比如css/style.css，而不是/css/style.css。这个细节在本地访问时看不出区别，但部署到 GitHub Pages 项目站点后，如果使用了绝对路径，样式和脚本很容易全部 404。

5.4 确认页面内容后再进入发布阶段

本地确认无误后，先不要急着写更多功能。先把“本地开发 → 推送部署 → 公网访问”这条链路跑通，再逐步添加内容。

这样做有两点好处：第一，如果发布链路有问题，可以在最小状态时暴露出来，便于排查；第二，后续每次迭代都沿着已验证的路径走，效率更高。

6. 推送到 GitHub 并开启 Pages 发布

6.1 本地初始化并推送

先初始化 Git 仓库，把当前目录下的所有文件提交：

git init git add . git commit -m "feat: 初始化个人网站" git branch -M main

然后把本地仓库关联到远程仓库。请将下面的仓库地址替换成你自己的：

git remote add origin https://github.com/你的用户名/my-personal-site.git git push -u origin main

执行完git push后，登录 GitHub 网页端，刷新仓库页面，应该能看到刚刚提交的文件。

6.2 在 GitHub 上开启 Pages

进入仓库的 Settings → Pages 页面。

这里有两种常见配置方式：

方式一：从分支部署。在 Source 选项中选择 “Deploy from a branch”，Branch 选择main，目录选择/root。如果项目是纯静态结构，且入口 HTML 文件在仓库根目录，选这个最简单。

方式二：从 GitHub Actions 部署。如果项目有独立的构建步骤，推荐用这种方式。Pages 设置里 Source 选择 “GitHub Actions”，然后往仓库里添加一个工作流文件。

对个人网站来说，我的建议是直接用方式二，原因很简单：它能完整演示“push 即发布”的自动化流程，后续项目变大时也不需要来回改配置。

6.3 编写 GitHub Actions 自动构建工作流

在项目根目录创建.github/workflows/deploy.yml：

name: Deploy to GitHub Pages on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Upload Pages artifact uses: actions/upload-pages-artifact@v3 with: path: dist deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4

这个工作流文件里的关键点：

• on.push.branches表示只有 main 分支的推送才会触发构建和部署；
• actions/checkout把仓库代码拉取到构建环境中；
• actions/setup-node指定 Node.js 版本；
• npm ci是根据 lock 文件安装依赖，比npm install更稳定；
• npm run build执行项目构建，生成dist目录；
• upload-pages-artifact把dist目录上传为 Pages 构件；
• deploy-pages真正执行发布。

如果你的项目没有 package.json，也不依赖构建步骤，那么 build 阶段可以直接把path: dist改成path: .，或者干脆不用 Actions，直接用 6.2 中的方式一部署根目录。

6.4 推送工作流文件并等待构建

把工作流文件加入 Git，并推送到 GitHub：

git add .github/workflows/deploy.yml git commit -m "ci: 添加 GitHub Pages 自动部署工作流" git push

推送完成后，到仓库的 Actions 页面查看运行状态。第一次运行可能需要几十秒到几分钟。看到绿色对勾，说明构建和部署都成功了。

6.5 访问你的线上网站

部署完成后，站点地址通常在仓库的 Settings → Pages 页面可以看到。如果不确定，可以先尝试访问：

https://你的用户名.github.io/my-personal-site/

如果打开后能看到你本地预览的页面，恭喜你，网站已经真正上线了。把链接发给你朋友之前，先在自己手机和电脑的浏览器上都打开一次，确认没有样式丢失或资源 404 的问题。

7. 每次迭代如何自动化发布

7.1 从“手动上传”到“push 即发布”

假设现在网站已经上线，你想改一下首页的标题，再新增一个作品卡片。传统方式：本地改 → 打包 → 连接服务器 → 上传。新方式：让 Codex 改 → 本地预览 → 提交推送 → 自动部署。

下面是用 Codex 修改网站的典型流程：

codex

然后告诉 Codex：

请把首页的标题从“你好，我是前端开发者”改为“你好，我是全栈开发者”， 并在作品集页面新增一个卡片，展示我最近做的图书管理系统的项目。 项目结构保持现有方式不变。

Codex 改完后，本地打开页面确认变化。如果没有问题，直接在终端执行：

git add . git commit -m "feat: 更新首页标题，新增作品卡片" git push

push 之后，GitHub Actions 会自动执行构建和部署。过一两分钟刷新线上网站，就能看到最新内容了。

7.2 封装一个一键发布脚本

如果你觉得三条命令还是繁琐，可以在项目根目录放一个deploy.sh脚本：

#!/bin/bash set -e echo "===== 开始发布 =====" git add . git commit -m "$1" git push echo "===== 发布成功，等待 GitHub Actions 构建 ====="

然后给它执行权限：

chmod +x deploy.sh

以后发布只需要执行：

./deploy.sh "feat: 更新个人简介"

这个脚本的主要价值，是把发布动作压缩成一条命令，并防止你忘了 commit 或 push。它没有做太复杂的逻辑，因为越简单越不容易出错。

7.3 让 Codex 也学会你的发布流程

Codex 支持通过项目配置文件或说明文件来理解项目的工作方式。你可以在项目根目录放一个CLAUDE.md或者 Codex 约定的说明文件，把构建命令和发布流程写进去。这样 Codex 在修改代码后，会更清楚这个项目是怎么跑起来、怎么构建、怎么发布的。

下面是一个最小示例：

# 项目说明 这是一个纯静态个人网站项目。 - 本地预览：直接打开 index.html，或使用 Vite 开发服务器 - 构建命令：npm run build - 产物目录：dist - 发布方式：推送 main 分支，GitHub Actions 自动部署到 GitHub Pages

这样做的目的，不是让 Codex 自动完成发布，而是让 Codex 在生成代码时更贴合项目的工程约定。后续如果你让它增加页面，它会更倾向于使用项目已有的风格和结构。

8. 常见问题与排查方法

8.1 问题速查表

8.2 关于 Codex 运行报错的一些补充

Codex 在使用过程中会出现一些报错，其中几类比较典型。

第一类是模型相关错误。例如提示模型不支持某个请求方式。这类问题通常和你配置的模型服务有关。如果你使用的是第三方兼容服务，需要确认该服务是否完整实现了 Codex 所需的接口协议。社区中反馈较多的一个例子是：使用基于 DeepSeek 类模型的兼容服务时，接口返回类似the reasoning_content in the thinking mode must be passed back to the api的 400 错误。这通常说明服务商的思维链字段与 Codex 使用的 OpenAI 协议不兼容，需要模型服务商侧适配，或者在该服务商的配置中关闭相应模式。遇到这类问题，优先检查模型服务商提供的接入文档，而不是反复重试。

第二类是上下文超限。提示类似ran out of room in the model's context window。这说明当前会话里塞了太多内容。解决办法是结束当前会话，新开一个会话继续，或者把任务拆得再细一些。

第三类是配置原因导致无法使用模型。比如在配置第三方模型或自定义模型时，填写的模型名不在服务商支持的列表中，也会报错。排查思路是先回退到默认配置，确认 Codex 能正常工作，再逐步引入其他配置。

8.3 一个容易忽略的问题：构建目录到底对不对

很多新手第一次配置 Actions 时，最容易出错的地方是upload-pages-artifact的path。

如果项目使用 Vite 或 Webpack 这类构建工具，构建产物默认在dist或build目录。但你未必清楚自己的项目用的是哪个目录。排查方法很简单：看项目根目录下有没有vite.config.js、webpack.config.js这类配置文件，里面写的输出目录在哪，Actions 里就填哪。

如果项目根本没有构建步骤，纯 HTML/CSS/JS 平铺在根目录，那就不需要刻意使用 dist。直接使用分支部署根目录，或者把 Actions 里的path改为.。不要机械照搬别人的配置。

9. 最佳实践与工程建议

9.1 项目结构要清晰，产物目录要和源码分离

个人网站项目虽然不大，但依然建议区分源码与构建产物。源码放在src或项目根目录的对应文件夹里，构建产物单独输出到dist。

如果使用 Actions 自动构建，dist目录不需要提交到 Git 仓库。建议在.gitignore中加入：

node_modules/ dist/ .DS_Store *.log

这样做的好处是：仓库只保存源代码，不保存生成结果，代码变更记录更清晰，也不会出现“本地构建产物和远程产物不一致”的困惑。

9.2 分支策略从第一天就定好

个人网站的复杂度不需要很花哨的分支策略，但一定要定一条规则：main 分支永远是可发布状态。

开发新功能时，可以在另一个分支上进行，验证没问题后合并到 main，再推送触发部署。避免直接在 main 上提交一堆半成品，然后一个个 push，导致线上网站频繁处于中间状态。

如果你是单人开发，这个规则看起来多余。但一旦你想引入更多自动化检查，或者未来有人参与协作，一个稳定的 main 分支会让你少踩很多坑。

9.3 安全边界：密钥和令牌绝不入库

GitHub Pages 仓库最常见的情况是 Public。也就是说，所有提交到仓库的历史记录都是公开的。任何 API Key、Token、密码、云服务密钥，一旦被 push 进仓库，即使马上删除，历史记录里也可能还留着。

在使用 Codex 时，也要注意它生成的代码里不会包含你的真实密钥。如果 Codex 需要读取配置，优先使用环境变量或本地配置文件，并把这类文件加入.gitignore。

9.4 发布前做一次完整的本地验证

不要依赖“push 上去再说”的心态。发布前至少确认三件事：第一，本地执行构建命令能成功；第二，打开构建产物页面，确认样式和脚本正常；第三，检查资源路径是否都是相对路径。

尤其是第三点，在很多静态站项目里，一旦配置了路由或使用了/开头的绝对路径，部署到 Pages 项目站点后就会出现资源加载失败。只要在本地先看一遍构建产物，这个问题很容易提前发现。

9.5 关于成本和卡顿的预期管理

GitHub Pages 和 GitHub Actions 对个人项目有免费额度，对大多数个人网站来说完全够用。但如果你把网站当生产环境，还是要关注 GitHub 服务可用性和政策变化。免费服务解决的是“没有成本部署个人站”的需求，不代表它承诺企业级 SLA。

如果你只是想要一个个人名片、作品集、技术博客，这套方案是性价比最高的选择。如果你需要后端接口、数据库、用户系统，那 Pages 不是你该考虑的方案，请换成服务器或云函数等方案。

10. 总结与后续学习方向

到这一步，你其实已经完成了一条完整的“AI 编程 + Git 托管 + 自动部署”链路：

• 用 Codex 生成和修改网站代码；
• 本地预览和构建验证；
• 推送到 GitHub 触发 Actions 自动构建；
• GitHub Pages 免费托管静态网站；
• 后续每次改动，push 即发布。

这套组合真正解决的问题，不只是一个“免费放网页的地方”。它把发布从“手动上传”的重复劳动中解放出来，让你每一次修改都有提交记录、有回滚能力、有自动化构建兜底。这才是它比传统 FTP 上传方式更有价值的地方。

下一步可以深入研究的方向有三个：第一，绑定自定义域名，并为自己的域名配置 HTTPS；第二，把个人网站升级为技术博客，例如使用静态博客生成器，配合 Pages 自动发布；第三，在 Actions 中加入更多质量检查，比如 lint、HTML 校验、图片压缩。每一条路都能让你对“从代码到上线”的链路理解得更深。

建议先不要急着增加复杂功能，按照本文流程完整跑一遍。第一次手动完成后，你会发现后续迭代快得多。把这条链路保存在你的工作流里，以后做任何静态网站项目，都能直接复用。