花了一下午让 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 传统发布方式与新工作流对比先看传统方式本地写代码手动执行构建命令打开服务器面板或 FTP 工具上传文件到服务器指定目录手动下载日志排查问题如果需要回滚手动把备份文件重新上传。这套流程最大的问题不是每一步有多难而是每一步都需要人记得执行、执行正确、按顺序执行。只要有一次遗漏线上就可能出问题。再看新方式用 Codex 写代码或改代码本地预览确认没有问题执行 git add、git commit、git pushGitHub Actions 自动构建GitHub Pages 自动更新线上网站如果需要回滚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 langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title我的个人网站/title link relstylesheet hrefcss/style.css / /head body nav a hrefindex.html首页/a a hrefabout.html关于我/a a hrefworks.html作品集/a /nav header h1你好我是前端开发者/h1 p这里展示我的技术作品与个人介绍。/p /header script srcjs/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.ymlname: 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/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Upload Pages artifact uses: actions/upload-pages-artifactv3 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-pagesv4这个工作流文件里的关键点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并推送到 GitHubgit 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 pushpush 之后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 问题速查表问题现象可能原因排查方式解决方案本地预览正常外网打不开没有部署只访问了 localhost确认访问的是 github.io 地址按第 6 章完成 Pages 部署页面能打开但样式和图片 404资源使用了绝对路径子路径部署时路径失效打开浏览器控制台查看请求失败的文件把/css/style.css改为css/style.css相对路径访问仓库地址返回 404页面没有部署到根目录检查 Settings → Pages 中的 Source 设置确认部署目录下有 index.htmlGitHub Actions 构建失败Node 版本不兼容、依赖安装失败查看 Actions 日志定位失败步骤调整 Node 版本删除 lock 文件重新 install修改推送后线上内容没变构建还在进行中查看 Actions 页面运行状态等待构建完成或检查是否 push 到 main 分支自定义域名不生效DNS 解析未完成、Pages 未配置域名检查域名解析记录和 Settings → Pages等待解析生效在 Pages 设置中填入域名Codex 执行任务过程中卡住网络问题、上下文过长查看 Codex 日志新开会话重启 Codex或把任务拆成更小的步骤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 models 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 校验、图片压缩。每一条路都能让你对“从代码到上线”的链路理解得更深。建议先不要急着增加复杂功能按照本文流程完整跑一遍。第一次手动完成后你会发现后续迭代快得多。把这条链路保存在你的工作流里以后做任何静态网站项目都能直接复用。
用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 传统发布方式与新工作流对比先看传统方式本地写代码手动执行构建命令打开服务器面板或 FTP 工具上传文件到服务器指定目录手动下载日志排查问题如果需要回滚手动把备份文件重新上传。这套流程最大的问题不是每一步有多难而是每一步都需要人记得执行、执行正确、按顺序执行。只要有一次遗漏线上就可能出问题。再看新方式用 Codex 写代码或改代码本地预览确认没有问题执行 git add、git commit、git pushGitHub Actions 自动构建GitHub Pages 自动更新线上网站如果需要回滚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 langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title我的个人网站/title link relstylesheet hrefcss/style.css / /head body nav a hrefindex.html首页/a a hrefabout.html关于我/a a hrefworks.html作品集/a /nav header h1你好我是前端开发者/h1 p这里展示我的技术作品与个人介绍。/p /header script srcjs/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.ymlname: 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/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Upload Pages artifact uses: actions/upload-pages-artifactv3 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-pagesv4这个工作流文件里的关键点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并推送到 GitHubgit 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 pushpush 之后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 问题速查表问题现象可能原因排查方式解决方案本地预览正常外网打不开没有部署只访问了 localhost确认访问的是 github.io 地址按第 6 章完成 Pages 部署页面能打开但样式和图片 404资源使用了绝对路径子路径部署时路径失效打开浏览器控制台查看请求失败的文件把/css/style.css改为css/style.css相对路径访问仓库地址返回 404页面没有部署到根目录检查 Settings → Pages 中的 Source 设置确认部署目录下有 index.htmlGitHub Actions 构建失败Node 版本不兼容、依赖安装失败查看 Actions 日志定位失败步骤调整 Node 版本删除 lock 文件重新 install修改推送后线上内容没变构建还在进行中查看 Actions 页面运行状态等待构建完成或检查是否 push 到 main 分支自定义域名不生效DNS 解析未完成、Pages 未配置域名检查域名解析记录和 Settings → Pages等待解析生效在 Pages 设置中填入域名Codex 执行任务过程中卡住网络问题、上下文过长查看 Codex 日志新开会话重启 Codex或把任务拆成更小的步骤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 models 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 校验、图片压缩。每一条路都能让你对“从代码到上线”的链路理解得更深。建议先不要急着增加复杂功能按照本文流程完整跑一遍。第一次手动完成后你会发现后续迭代快得多。把这条链路保存在你的工作流里以后做任何静态网站项目都能直接复用。