之前用 Codex 生成网站本地预览一切正常但把地址发给朋友时对方完全打不开。后来把代码推到 GitHub 上托管又发现每次改点东西都要手动重新构建、上传非常容易出错。这篇文章我整理了一套可以照抄的完整流程用 Codex 快速开发网站再配合 GitHub Pages 免费托管并借助 GitHub Actions 实现推送代码后自动部署基本告别“手动上传”。不管你之前是否用过 Codex只要你对 AI 辅助编程感兴趣并且想把自己的个人主页、简历页、作品集快速挂到公网都可以照着文章走一遍。读完你会明白 localhost 为什么不能被别人访问也掌握一套从 0 到 1 的免费上线方案。1. 为什么本地能访问别人却访问不了1.1 localhost 只能代表“本机”很多刚接触网站开发的同学用 Codex 生成好页面后在浏览器里打开http://localhost:8000看到网站正常显示就觉得“网站做完了”。但把链接发给别人时对方看到的却是无法访问。原因是localhost这个地址有非常明确的语义它永远指向“当前这台电脑自己”。你本机打开它没问题是因为浏览器和服务器都运行在同一台机器上别人打开它浏览器仍然会尝试访问“别人自己的电脑”当然找不到你的网站。如果进一步想就算你把 IP 换成局域网地址比如192.168.1.100:8000也只有连接同一个路由器的设备能访问。再往外面走还需要公网 IP、端口映射、防火墙放行等一堆配置。而且这种方案还依赖你的电脑持续开机一旦关机、休眠或断网网站立刻下线。问题的本质是Codex 生成的个人网站本质上是一堆 HTML、CSS、JavaScript 静态文件它并没有“必须运行在你电脑上”的硬性要求。既然只是静态资源完全可以放到一个 24 小时在线的静态托管平台上让全世界都能访问。1.2 手动上传部署的效率和风险网站做出来之后第二件让人头疼的事就是更新。很多人的第一反应是“把生成的文件夹打包发到服务器/网盘”或者手工把dist目录里的文件拖到某个地方覆盖。这种方案有几个问题流程完全靠人工一旦文件多、改得频繁很容易漏传或传错位置。没有版本概念改坏了想回滚只能靠自己记得的“上一份备份”。多人协作时并发覆盖基本无法避免。如果上传过程中网络中断线上可能同时存在新旧混杂的文件页面处于半坏状态。真正工程化的做法是让部署变成一条自动化流水线你只需要把代码推到 Git 仓库构建和发布由流水线自动完成历史版本、回滚、日志全部有迹可循。1.3 方案总览Codex GitHub Pages 全自动部署本文要搭建的完整链路如下用 Codex 生成或修改网站代码。本地提交 Git并推送到 GitHub 仓库。GitHub Actions 检测到推送自动执行构建和部署。GitHub Pages 把静态文件发布到公网并自动提供 HTTPS 访问。这套方案的好处很明显托管免费、部署自动、地址稳定、支持自定义域名而且只要代码仓库在网站就一直在不依赖你的电脑是否开机。2. 核心概念Codex 与 GitHub Pages2.1 Codex 是做什么的Codex 是 OpenAI 推出的 AI 编程智能体产品你可以把它理解成一个“住在项目里的开发者”你给它一句自然语言描述它就能在项目里生成代码、修改文件、执行命令甚至帮你排查报错。它和普通聊天 AI 最大的区别在于“会动手改东西”而不是只输出一段代码让你自己复制。Codex 目前有几种常见使用形态命令行工具CLI适合在终端里操作项目。桌面版应用适合不熟悉命令行的用户。VS Code 等 IDE 插件适合边写代码边让 AI 辅助。API 接入方式可以接入官方模型服务也可以根据服务商说明接入第三方模型接口。不同版本的安装方式和认证流程差别较大建议以 OpenAI 官方文档为准。需要特别说明的是使用 Codex 前必须完成账号登录或 API Key 配置如果接入的是第三方模型服务则要严格按照该服务商提供的接口说明填写配置这个环节最容易出错后面常见问题部分会展开。2.2 GitHub Pages 是什么GitHub Pages 是 GitHub 提供的静态网站托管服务。它的使用模型非常简单你把一个仓库里的静态文件交给 GitHubGitHub 生成一个所有人都能访问的网页地址。它的几个优点非常适合个人网站免费不需要单独买服务器。自动启用 HTTPS访问安全性由 GitHub 处理。自带 CDN 加速全球访问体验较好。支持绑定自定义域名。与 Git 天然集成每次提交都能留下历史记录随时可以回滚。但它也有非常明确的边界只能托管纯静态文件。所谓“静态”是指浏览器直接能运行的内容比如 HTML、CSS、JavaScript、图片、字体等。如果网站需要后端服务、数据库、用户登录、动态 APIGitHub Pages 就不适用了。个人主页、作品集、简历页、文档站、产品介绍页都在它的适用范围内。2.3 为什么这个组合适合个人网站Codex 负责“快速写”GitHub 负责“可靠存”Pages 负责“免费放”Actions 负责“自动发”。这个组合几乎是为个人静态网站量身定做的。你只需要维护一个 Git 仓库剩下的发布流程全部自动化。以后想改网站继续让 Codex 改代码改完提交推送几十秒后线上就更新了不再需要手动构建、上传、覆盖这一套繁琐操作。3. 环境准备与版本说明在开始之前我们需要把本地环境准备好。以下工具都是搭建过程中会用到的版本方面不写死具体数值因为项目不同、系统不同需要的版本可能不一样关键是确认这些工具已经安装且能正常执行。3.1 准备工具清单工具用途说明Git版本管理和代码推送建议安装最新稳定版GitHub 账号创建远程仓库免费账号即可Node.js本地预览和前端构建建议使用 18 或更高的 LTS 版本按项目实际调整Codex生成和修改网站代码可以选择 CLI、桌面版或 IDE 插件如果你的网站只是纯 HTML/CSS/JS不依赖 npm 构建那么 Node.js 不是必须的但如果你想用 Vite、React、Vue 这类现代前端工程就一定要装 Node.js。本文的基础案例用纯静态网页演示进阶案例会展示带构建步骤的写法。3.2 Codex 的安装与认证Codex 的安装方式请以当前版本的官方文档为准因为官方更新比较频繁命令行安装包名、桌面版下载入口、插件市场名称都可能变化。大致思路是在官方渠道下载对应系统的安装包或使用包管理器安装。启动 Codex按提示完成账号登录或者配置 API Key。如果使用第三方模型服务在配置文件中填写服务商提供的接口地址、模型名称、密钥等信息。完成后建议先跑一个小任务确认环境正常比如让 Codex 生成一个最简单的 HTML 文件确认它能正确读取项目目录并写文件。3.3 验证本地环境在终端里执行下面的命令确认基础工具可用git --version node --version npm --version codex --version这里把codex --version也列出来了但如果你的 Codex 是桌面版应用可能没有这个命令行入口那么可以忽略该命令改用桌面版本身检查安装状态。只要 git 和 node/npm 能输出版本号本地基础环境就基本没问题。4. 用 Codex 快速生成一个个人网站这一节我们正式进入实战用 Codex 生成一个完整的静态个人网站。4.1 创建项目目录先在本地创建一个干净的目录并进入该目录mkdir my-personal-site cd my-personal-sitemy-personal-site就是我们网站项目的根目录。后续 Codex 生成的文件、Git 版本记录都会放在这里。4.2 向 Codex 描述需求在项目目录中打开 Codex然后输入类似下面这样的需求描述你是资深前端工程师请帮我生成一个个人网站主页要求如下 1. 最上方展示姓名、头像占位图、一句话简介。 2. 页面包含“关于我”“项目作品”“联系方式”三个板块。 3. 风格简约干净配色偏现代移动端自适应。 4. 不要使用前端框架直接生成 index.html、style.css、script.js 三个文件。 5. script.js 里实现平滑滚动到各个板块的功能。不要小看这段描述它其实交代了输出格式、技术栈、页面结构、交互效果Codex 拿到这样的任务后会直接在项目目录下创建文件。如果它没有自动创建你可以在结果里点击应用或者让它“把代码写入 index.html / style.css / script.js”。Codex 生成完后可以执行下面命令查看项目结构ls -l正常情况下你应该能看到index.html、style.css、script.js三个文件它们就是网站的源码。4.3 本地预览与验证因为这是纯静态网页不需要构建直接起一个本地静态服务即可预览。在项目根目录执行python3 -m http.server 8000如果你的系统没有 python3也可以使用 Node 的npx servenpx serve -l 8000然后打开浏览器访问http://localhost:8000你应该能看到 Codex 生成的个人网站页面。注意此时页面只有你能访问。这个地址就是 1.1 节说的问题所在下一步我们要把它推到 GitHub 上让网站真正“上线”。5. 推送到 GitHub 并开启 Pages 托管5.1 在 GitHub 创建仓库登录 GitHub点击右上角 “New repository” 创建新仓库。有两个关键点仓库必须是 Public公开GitHub Pages 免费托管只支持公开仓库场景。仓库命名会影响最终访问地址。GitHub Pages 的访问地址规则是如果仓库名是你的用户名.github.io那么访问地址是https://你的用户名.github.io/。如果仓库名是其他任意名字比如my-personal-site那么访问地址是https://你的用户名.github.io/my-personal-site/。创建时暂不勾选 “Add a README file”因为你本地已经有项目文件了避免推送时产生冲突。5.2 本地 Git 提交并推送在本地项目根目录执行如下命令把项目变成 Git 仓库并推送到 GitHubgit init git add . git commit -m feat: 初始化个人网站 git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main注意把你的用户名和你的仓库名替换成你自己的信息。git branch -M main是把本地默认分支改名为main这能保证与 GitHub 仓库的主分支一致避免分支名不匹配的困惑。推送成功后打开 GitHub 仓库页面你应该能在代码列表里看到刚才提交的index.html、style.css、script.js。5.3 开启 GitHub Pages 并完成首次发布进入仓库的Settings设置页面找到左侧菜单中的Pages。在 “Build and deployment” 区域将 Source来源从 “Deploy from a branch” 切换为GitHub Actions。这个步骤非常关键。选择GitHub Actions后GitHub 会等待仓库中的 Actions 工作流来发布页面。因为我们还没创建工作流先不要着急这正是下面一节要解决的问题。如果你只是想快速验证“别人能不能访问”也可以暂时选择 “Deploy from a branch”然后选择main分支和根目录保存后等待一两分钟GitHub 就会生成首次发布的地址。但从长期迭代来看我更推荐用 Actions因为它是把“手动上传”变成“自动发布”的核心。6. 自动化部署解决每次手动上传的痛点6.1 为什么不用手动上传很多同学知道 GitHub Pages 支持“从分支部署”后会直接选择 main 分支然后每次发布时手动把构建产物复制到仓库里再推送一遍。这种方式虽然也能更新网站但构建产物和源码混在一起仓库越来越乱而且仍然没有摆脱“手动”两个字。正确做法是源码仓库里只放源代码部署动作交给 GitHub Actions 自动执行。你每次推送代码Actions 都会自动运行工作流处理构建、上传、发布全程不需要你碰任何产物文件。6.2 编写 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/checkoutv4 - name: Setup Pages uses: actions/configure-pagesv5 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: . - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这段工作流的作用是on.push.branches只有在 main 分支发生推送时才触发部署。permissions给工作流写 Pages 环境、签发令牌的权限这是 GitHub 官方要求的。concurrency同一时间只允许一个部署任务运行新的推送会取消进行中的旧任务。actions/checkoutv4把仓库代码拉取到 Actions 运行环境中。actions/configure-pagesv5配置 Pages 环境。actions/upload-pages-artifactv3把指定目录打包成部署产物这里上传的是仓库根目录.因为文章示例是纯静态网站源码本身就是可发布的静态文件。actions/deploy-pagesv4把产物发布到 GitHub Pages。如果你使用的 Actions 版本在将来发生变化请以 GitHub Actions Marketplace 上的最新版本为准。这个示例把“源码即运行文件”的场景覆盖了非常简洁。6.3 推送工作流并验证自动部署在本地把工作流文件提交并推送git add . git commit -m ci: 添加 GitHub Pages 自动部署工作流 git push推送完成后打开仓库的Actions页面能看到一个名为 “Deploy to GitHub Pages” 的工作流正在运行。等待它跑完状态变为绿色对勾说明部署成功。然后打开 5.1 节确定的访问地址如果仓库名是用户名.github.io访问https://用户名.github.io/。如果仓库名是普通名字访问https://用户名.github.io/仓库名/。这时候把链接发给任何人对方都能打开你的个人网站了。6.4 带前端构建流程的进阶写法如果你的网站是用 Vite、React、Vue 这类工具开发的源码中并不存在可以直接使用的静态文件而是需要通过npm install和npm run build生成一个dist目录。这种情况下只要修改工作流中的 build 步骤即可name: Deploy Vite Site 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 cache: npm - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Setup Pages uses: actions/configure-pagesv5 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: dist - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这段工作流和基础版的区别是增加了 Node 环境配置、依赖安装和构建步骤最终把dist目录作为部署产物上传。这里有一个非常容易踩的坑如果仓库不是用户名.github.io而是普通仓库名部署后访问地址会带一个子路径。Vite 默认认为应用部署在域名根路径所以需要去vite.config.js里设置 baseexport default { base: /仓库名/, }设置完成后重新推送构建出的资源路径才会指向正确的子路径否则页面能打开但样式和脚本文件全部加载失败。7. 常见问题与排查思路下面把实际使用中最高频的问题整理成一个总览表再逐个展开说明。问题现象常见原因解决思路访问地址 404仓库名、分支或部署方式不对检查仓库名规则和 Pages 设置页面能打开但样式丢失资源路径写死为绝对路径改用相对路径或设置 base推送后页面不更新CDN 缓存或 Actions 未触发等待几分钟并查看 Actions 日志Actions 部署失败工作流权限或 Pages 来源设置不对检查 permissions 和 SourceCodex 接口报错模型服务配置不匹配核对模型名称、接口格式、密钥Codex 运行中断上下文窗口溢出新开会话或精简项目上下文7.1 访问地址 404这是新手最容易遇到的问题。先检查 GitHub 仓库名如果你的仓库名是用户名.github.io直接访问根地址。如果你的仓库名是普通名字访问地址必须带/仓库名/后缀。然后检查 Pages 设置确认 Source 是GitHub Actions并且最新一次 Actions 运行是成功的。如果你的仓库历史记录里曾经用过 “Deploy from a branch”但后来改成 Actions偶尔也会出现设置状态不一致可以把 Source 切回去再切回 Actions强制刷新一次发布流程。7.2 页面能打开但样式丢失这种情况通常是 HTML 里引用 CSS/JS 的路径写死了。例如在index.html里写了/style.css这个路径在本地根路径下没问题但部署到/my-personal-site/子路径后浏览器会去域名根目录找style.css自然找不到。解决办法是使用相对路径把link relstylesheet href/style.css改为link relstylesheet href./style.css或者改成link relstylesheet hrefstyle.css相对路径的好处是无论部署在根路径还是子路径浏览器都会以当前页面所在目录为基准去加载资源。7.3 推送后页面没有更新GitHub Pages 有 CDN 缓存推送成功后线上可能不会立刻生效通常需要等一两分钟。你可以强制刷新浏览器或者在隐私无痕窗口里打开页面验证。另外要检查 Actions 是否真的触发了只有推送到main分支并且工作流文件存在于 main 分支时才会自动执行。如果你是在其他分支推送的Actions 不会运行。7.4 Codex 接入模型服务时报错如果你不是使用官方默认配置而是接了第三方模型服务有时会看到类似下面这类报错提示某个模型名不被支持。提示返回结果格式不符合 Codex 预期。提示思考模式下缺少某个必须字段服务端返回 HTTP 400。这类问题的根因通常不是 Codex 本身坏了而是模型名称、接口格式或请求参数与服务商要求不一致。排查思路如下确认填写的模型名称与模型服务商实际提供的名称完全一致。确认接口地址是否填对不要出现多余空格或末尾斜杠。确认是否开启了思考模式如果服务商要求回传reasoning_content字段而本地版本不支持可以考虑关闭思考模式或升级 Codex 到支持该字段的版本。查看 Codex 日志或终端输出找到真实的upstream_status和cause字段它们会直接告诉你是哪一步请求失败了。需要注意不同模型服务商的能力差异很大有的模型支持思考模式有的不支持支持思考模式的模型对请求格式的要求也可能不同。建议先按服务商提供的官方示例跑通一次再切换 Codex 默认模型这样能更快定位问题。7.5 上下文窗口溢出如果你在同一个 Codex 会话里持续开发很久可能会看到类似 “ran out of room in the models context window” 的提示。这说明当前会话累积的上下文已经超出了模型的窗口上限。解决方案很直接新开一个会话或者在重新开始时只描述当前需要修改的问题不要重复粘贴大量历史代码。Codex 读取项目文件的方式和聊天粘贴不同它通常只会读取它认为需要的文件所以尽量避免在对话里堆叠大段代码让 Codex 自己去读文件会更省上下文。7.6 想绑定自定义域名想让网站不使用用户名.github.io而用自己的域名可以在仓库 Settings - Pages 中找到 “Custom domain”填入你的域名然后在 DNS 服务商处添加一条解析记录。绑定后 GitHub 会自动签发 HTTPS 证书证书生效需要等待几分钟到几十分钟不等。需要注意如果使用自己的域名并且仓库不是用户名.github.io同样要注意子路径和资源路径的问题。8. 最佳实践与工程建议到这里整条自动化部署链路已经跑通了。最后分享一些我在实际使用中觉得重要的工程化建议能帮你把这个方案用得更稳、更省心。8.1 仓库目录与提交规范保持仓库目录整洁工作流配置文件放在.github/workflows/下源码按项目结构组织不要把构建产物dist/提交到仓库里。可以在项目根目录创建.gitignore文件node_modules/ dist/ .DS_Store提交信息建议使用清晰的约定式风格例如feat: 新增项目展示区域 fix: 修复移动端导航栏错位 ci: 更新部署工作流这样的好处是以后想查“哪次改动导致问题”直接看提交历史就能定位。8.2 静态资源路径与版本管理无论使用哪种前端方案资源路径问题都是 GitHub Pages 子路径部署的头号坑。如果你用 Vite记得配置 base如果你写纯 HTML尽量使用相对路径。另外如果你的网站引用了大量图片、字体建议把文件放在统一目录里比如assets/并且用语义化文件名。大型文件要压缩后再提交避免仓库体积膨胀和页面加载缓慢。8.3 缓存、安全与隐私边界GitHub Pages 自带缓存线上更新不会立即生效这既是优点也是坑。建议在页面里给静态资源加版本号例如style.css?v2这样修改样式后浏览器会重新加载文件。安全方面要特别注意GitHub Pages 是公开站点任何人都能访问如果你创建的是公开仓库代码也会被所有人看到。绝对不要把 API Key、数据库密码、私钥等敏感信息提交到仓库里。Codex 在生成代码时如果涉及配置项也最好用环境变量或单独的管理方式不要硬编码在源码中。8.4 用 Codex 持续迭代的个人工作流当网站上线后你的日常迭代流程可以简化为在本地启动 Codex 会话描述要修改的内容。Codex 修改代码进行本地预览调整样式和交互。检查无误后提交 Git推送 main 分支。打开 GitHub Actions 页面确认部署成功。刷新线上地址验证更新效果。如果改了没什么把握的样式或功能建议先本地预览确认再推送到线上。虽然 Actions 部署很快但线上环境毕竟会暴露给访问者没必要让访问者替你测试。9. 总结与下一步学习建议这套流程的核心其实不是某个单一工具而是把 AI 编程、Git 版本管理、自动化部署三个能力组合起来形成一个完整的个人网站发布闭环。Codex 帮你省掉重复编码的时间和精力Git 帮你记录每个历史版本GitHub Actions 帮你把发布从手动操作变成自动行为GitHub Pages 则负责免费稳定地把网站呈现给全世界。如果你也卡在“本地能访问、别人访问不了”和“每次更新都要手动上传”这两个问题上建议先按文章里的基础案例完整跑一遍。不要一上来就追求复杂的设计和框架先用纯 HTML 页面打通整条链路再逐步引入构建工具、自定义域名、更多页面结构。下一步可以继续学习 Git 分支工作流、前端构建工具、GitHub Actions 的更多触发方式也可以研究如何给网站添加访问统计、SEO 标签和社交媒体分享卡片。等你把基础流程熟练之后再回头用 Codex 迭代网站体验会顺畅很多。 用Codex+GitHub Pages+Actions实现网站自动部署
之前用 Codex 生成网站本地预览一切正常但把地址发给朋友时对方完全打不开。后来把代码推到 GitHub 上托管又发现每次改点东西都要手动重新构建、上传非常容易出错。这篇文章我整理了一套可以照抄的完整流程用 Codex 快速开发网站再配合 GitHub Pages 免费托管并借助 GitHub Actions 实现推送代码后自动部署基本告别“手动上传”。不管你之前是否用过 Codex只要你对 AI 辅助编程感兴趣并且想把自己的个人主页、简历页、作品集快速挂到公网都可以照着文章走一遍。读完你会明白 localhost 为什么不能被别人访问也掌握一套从 0 到 1 的免费上线方案。1. 为什么本地能访问别人却访问不了1.1 localhost 只能代表“本机”很多刚接触网站开发的同学用 Codex 生成好页面后在浏览器里打开http://localhost:8000看到网站正常显示就觉得“网站做完了”。但把链接发给别人时对方看到的却是无法访问。原因是localhost这个地址有非常明确的语义它永远指向“当前这台电脑自己”。你本机打开它没问题是因为浏览器和服务器都运行在同一台机器上别人打开它浏览器仍然会尝试访问“别人自己的电脑”当然找不到你的网站。如果进一步想就算你把 IP 换成局域网地址比如192.168.1.100:8000也只有连接同一个路由器的设备能访问。再往外面走还需要公网 IP、端口映射、防火墙放行等一堆配置。而且这种方案还依赖你的电脑持续开机一旦关机、休眠或断网网站立刻下线。问题的本质是Codex 生成的个人网站本质上是一堆 HTML、CSS、JavaScript 静态文件它并没有“必须运行在你电脑上”的硬性要求。既然只是静态资源完全可以放到一个 24 小时在线的静态托管平台上让全世界都能访问。1.2 手动上传部署的效率和风险网站做出来之后第二件让人头疼的事就是更新。很多人的第一反应是“把生成的文件夹打包发到服务器/网盘”或者手工把dist目录里的文件拖到某个地方覆盖。这种方案有几个问题流程完全靠人工一旦文件多、改得频繁很容易漏传或传错位置。没有版本概念改坏了想回滚只能靠自己记得的“上一份备份”。多人协作时并发覆盖基本无法避免。如果上传过程中网络中断线上可能同时存在新旧混杂的文件页面处于半坏状态。真正工程化的做法是让部署变成一条自动化流水线你只需要把代码推到 Git 仓库构建和发布由流水线自动完成历史版本、回滚、日志全部有迹可循。1.3 方案总览Codex GitHub Pages 全自动部署本文要搭建的完整链路如下用 Codex 生成或修改网站代码。本地提交 Git并推送到 GitHub 仓库。GitHub Actions 检测到推送自动执行构建和部署。GitHub Pages 把静态文件发布到公网并自动提供 HTTPS 访问。这套方案的好处很明显托管免费、部署自动、地址稳定、支持自定义域名而且只要代码仓库在网站就一直在不依赖你的电脑是否开机。2. 核心概念Codex 与 GitHub Pages2.1 Codex 是做什么的Codex 是 OpenAI 推出的 AI 编程智能体产品你可以把它理解成一个“住在项目里的开发者”你给它一句自然语言描述它就能在项目里生成代码、修改文件、执行命令甚至帮你排查报错。它和普通聊天 AI 最大的区别在于“会动手改东西”而不是只输出一段代码让你自己复制。Codex 目前有几种常见使用形态命令行工具CLI适合在终端里操作项目。桌面版应用适合不熟悉命令行的用户。VS Code 等 IDE 插件适合边写代码边让 AI 辅助。API 接入方式可以接入官方模型服务也可以根据服务商说明接入第三方模型接口。不同版本的安装方式和认证流程差别较大建议以 OpenAI 官方文档为准。需要特别说明的是使用 Codex 前必须完成账号登录或 API Key 配置如果接入的是第三方模型服务则要严格按照该服务商提供的接口说明填写配置这个环节最容易出错后面常见问题部分会展开。2.2 GitHub Pages 是什么GitHub Pages 是 GitHub 提供的静态网站托管服务。它的使用模型非常简单你把一个仓库里的静态文件交给 GitHubGitHub 生成一个所有人都能访问的网页地址。它的几个优点非常适合个人网站免费不需要单独买服务器。自动启用 HTTPS访问安全性由 GitHub 处理。自带 CDN 加速全球访问体验较好。支持绑定自定义域名。与 Git 天然集成每次提交都能留下历史记录随时可以回滚。但它也有非常明确的边界只能托管纯静态文件。所谓“静态”是指浏览器直接能运行的内容比如 HTML、CSS、JavaScript、图片、字体等。如果网站需要后端服务、数据库、用户登录、动态 APIGitHub Pages 就不适用了。个人主页、作品集、简历页、文档站、产品介绍页都在它的适用范围内。2.3 为什么这个组合适合个人网站Codex 负责“快速写”GitHub 负责“可靠存”Pages 负责“免费放”Actions 负责“自动发”。这个组合几乎是为个人静态网站量身定做的。你只需要维护一个 Git 仓库剩下的发布流程全部自动化。以后想改网站继续让 Codex 改代码改完提交推送几十秒后线上就更新了不再需要手动构建、上传、覆盖这一套繁琐操作。3. 环境准备与版本说明在开始之前我们需要把本地环境准备好。以下工具都是搭建过程中会用到的版本方面不写死具体数值因为项目不同、系统不同需要的版本可能不一样关键是确认这些工具已经安装且能正常执行。3.1 准备工具清单工具用途说明Git版本管理和代码推送建议安装最新稳定版GitHub 账号创建远程仓库免费账号即可Node.js本地预览和前端构建建议使用 18 或更高的 LTS 版本按项目实际调整Codex生成和修改网站代码可以选择 CLI、桌面版或 IDE 插件如果你的网站只是纯 HTML/CSS/JS不依赖 npm 构建那么 Node.js 不是必须的但如果你想用 Vite、React、Vue 这类现代前端工程就一定要装 Node.js。本文的基础案例用纯静态网页演示进阶案例会展示带构建步骤的写法。3.2 Codex 的安装与认证Codex 的安装方式请以当前版本的官方文档为准因为官方更新比较频繁命令行安装包名、桌面版下载入口、插件市场名称都可能变化。大致思路是在官方渠道下载对应系统的安装包或使用包管理器安装。启动 Codex按提示完成账号登录或者配置 API Key。如果使用第三方模型服务在配置文件中填写服务商提供的接口地址、模型名称、密钥等信息。完成后建议先跑一个小任务确认环境正常比如让 Codex 生成一个最简单的 HTML 文件确认它能正确读取项目目录并写文件。3.3 验证本地环境在终端里执行下面的命令确认基础工具可用git --version node --version npm --version codex --version这里把codex --version也列出来了但如果你的 Codex 是桌面版应用可能没有这个命令行入口那么可以忽略该命令改用桌面版本身检查安装状态。只要 git 和 node/npm 能输出版本号本地基础环境就基本没问题。4. 用 Codex 快速生成一个个人网站这一节我们正式进入实战用 Codex 生成一个完整的静态个人网站。4.1 创建项目目录先在本地创建一个干净的目录并进入该目录mkdir my-personal-site cd my-personal-sitemy-personal-site就是我们网站项目的根目录。后续 Codex 生成的文件、Git 版本记录都会放在这里。4.2 向 Codex 描述需求在项目目录中打开 Codex然后输入类似下面这样的需求描述你是资深前端工程师请帮我生成一个个人网站主页要求如下 1. 最上方展示姓名、头像占位图、一句话简介。 2. 页面包含“关于我”“项目作品”“联系方式”三个板块。 3. 风格简约干净配色偏现代移动端自适应。 4. 不要使用前端框架直接生成 index.html、style.css、script.js 三个文件。 5. script.js 里实现平滑滚动到各个板块的功能。不要小看这段描述它其实交代了输出格式、技术栈、页面结构、交互效果Codex 拿到这样的任务后会直接在项目目录下创建文件。如果它没有自动创建你可以在结果里点击应用或者让它“把代码写入 index.html / style.css / script.js”。Codex 生成完后可以执行下面命令查看项目结构ls -l正常情况下你应该能看到index.html、style.css、script.js三个文件它们就是网站的源码。4.3 本地预览与验证因为这是纯静态网页不需要构建直接起一个本地静态服务即可预览。在项目根目录执行python3 -m http.server 8000如果你的系统没有 python3也可以使用 Node 的npx servenpx serve -l 8000然后打开浏览器访问http://localhost:8000你应该能看到 Codex 生成的个人网站页面。注意此时页面只有你能访问。这个地址就是 1.1 节说的问题所在下一步我们要把它推到 GitHub 上让网站真正“上线”。5. 推送到 GitHub 并开启 Pages 托管5.1 在 GitHub 创建仓库登录 GitHub点击右上角 “New repository” 创建新仓库。有两个关键点仓库必须是 Public公开GitHub Pages 免费托管只支持公开仓库场景。仓库命名会影响最终访问地址。GitHub Pages 的访问地址规则是如果仓库名是你的用户名.github.io那么访问地址是https://你的用户名.github.io/。如果仓库名是其他任意名字比如my-personal-site那么访问地址是https://你的用户名.github.io/my-personal-site/。创建时暂不勾选 “Add a README file”因为你本地已经有项目文件了避免推送时产生冲突。5.2 本地 Git 提交并推送在本地项目根目录执行如下命令把项目变成 Git 仓库并推送到 GitHubgit init git add . git commit -m feat: 初始化个人网站 git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main注意把你的用户名和你的仓库名替换成你自己的信息。git branch -M main是把本地默认分支改名为main这能保证与 GitHub 仓库的主分支一致避免分支名不匹配的困惑。推送成功后打开 GitHub 仓库页面你应该能在代码列表里看到刚才提交的index.html、style.css、script.js。5.3 开启 GitHub Pages 并完成首次发布进入仓库的Settings设置页面找到左侧菜单中的Pages。在 “Build and deployment” 区域将 Source来源从 “Deploy from a branch” 切换为GitHub Actions。这个步骤非常关键。选择GitHub Actions后GitHub 会等待仓库中的 Actions 工作流来发布页面。因为我们还没创建工作流先不要着急这正是下面一节要解决的问题。如果你只是想快速验证“别人能不能访问”也可以暂时选择 “Deploy from a branch”然后选择main分支和根目录保存后等待一两分钟GitHub 就会生成首次发布的地址。但从长期迭代来看我更推荐用 Actions因为它是把“手动上传”变成“自动发布”的核心。6. 自动化部署解决每次手动上传的痛点6.1 为什么不用手动上传很多同学知道 GitHub Pages 支持“从分支部署”后会直接选择 main 分支然后每次发布时手动把构建产物复制到仓库里再推送一遍。这种方式虽然也能更新网站但构建产物和源码混在一起仓库越来越乱而且仍然没有摆脱“手动”两个字。正确做法是源码仓库里只放源代码部署动作交给 GitHub Actions 自动执行。你每次推送代码Actions 都会自动运行工作流处理构建、上传、发布全程不需要你碰任何产物文件。6.2 编写 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/checkoutv4 - name: Setup Pages uses: actions/configure-pagesv5 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: . - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这段工作流的作用是on.push.branches只有在 main 分支发生推送时才触发部署。permissions给工作流写 Pages 环境、签发令牌的权限这是 GitHub 官方要求的。concurrency同一时间只允许一个部署任务运行新的推送会取消进行中的旧任务。actions/checkoutv4把仓库代码拉取到 Actions 运行环境中。actions/configure-pagesv5配置 Pages 环境。actions/upload-pages-artifactv3把指定目录打包成部署产物这里上传的是仓库根目录.因为文章示例是纯静态网站源码本身就是可发布的静态文件。actions/deploy-pagesv4把产物发布到 GitHub Pages。如果你使用的 Actions 版本在将来发生变化请以 GitHub Actions Marketplace 上的最新版本为准。这个示例把“源码即运行文件”的场景覆盖了非常简洁。6.3 推送工作流并验证自动部署在本地把工作流文件提交并推送git add . git commit -m ci: 添加 GitHub Pages 自动部署工作流 git push推送完成后打开仓库的Actions页面能看到一个名为 “Deploy to GitHub Pages” 的工作流正在运行。等待它跑完状态变为绿色对勾说明部署成功。然后打开 5.1 节确定的访问地址如果仓库名是用户名.github.io访问https://用户名.github.io/。如果仓库名是普通名字访问https://用户名.github.io/仓库名/。这时候把链接发给任何人对方都能打开你的个人网站了。6.4 带前端构建流程的进阶写法如果你的网站是用 Vite、React、Vue 这类工具开发的源码中并不存在可以直接使用的静态文件而是需要通过npm install和npm run build生成一个dist目录。这种情况下只要修改工作流中的 build 步骤即可name: Deploy Vite Site 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 cache: npm - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Setup Pages uses: actions/configure-pagesv5 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: dist - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这段工作流和基础版的区别是增加了 Node 环境配置、依赖安装和构建步骤最终把dist目录作为部署产物上传。这里有一个非常容易踩的坑如果仓库不是用户名.github.io而是普通仓库名部署后访问地址会带一个子路径。Vite 默认认为应用部署在域名根路径所以需要去vite.config.js里设置 baseexport default { base: /仓库名/, }设置完成后重新推送构建出的资源路径才会指向正确的子路径否则页面能打开但样式和脚本文件全部加载失败。7. 常见问题与排查思路下面把实际使用中最高频的问题整理成一个总览表再逐个展开说明。问题现象常见原因解决思路访问地址 404仓库名、分支或部署方式不对检查仓库名规则和 Pages 设置页面能打开但样式丢失资源路径写死为绝对路径改用相对路径或设置 base推送后页面不更新CDN 缓存或 Actions 未触发等待几分钟并查看 Actions 日志Actions 部署失败工作流权限或 Pages 来源设置不对检查 permissions 和 SourceCodex 接口报错模型服务配置不匹配核对模型名称、接口格式、密钥Codex 运行中断上下文窗口溢出新开会话或精简项目上下文7.1 访问地址 404这是新手最容易遇到的问题。先检查 GitHub 仓库名如果你的仓库名是用户名.github.io直接访问根地址。如果你的仓库名是普通名字访问地址必须带/仓库名/后缀。然后检查 Pages 设置确认 Source 是GitHub Actions并且最新一次 Actions 运行是成功的。如果你的仓库历史记录里曾经用过 “Deploy from a branch”但后来改成 Actions偶尔也会出现设置状态不一致可以把 Source 切回去再切回 Actions强制刷新一次发布流程。7.2 页面能打开但样式丢失这种情况通常是 HTML 里引用 CSS/JS 的路径写死了。例如在index.html里写了/style.css这个路径在本地根路径下没问题但部署到/my-personal-site/子路径后浏览器会去域名根目录找style.css自然找不到。解决办法是使用相对路径把link relstylesheet href/style.css改为link relstylesheet href./style.css或者改成link relstylesheet hrefstyle.css相对路径的好处是无论部署在根路径还是子路径浏览器都会以当前页面所在目录为基准去加载资源。7.3 推送后页面没有更新GitHub Pages 有 CDN 缓存推送成功后线上可能不会立刻生效通常需要等一两分钟。你可以强制刷新浏览器或者在隐私无痕窗口里打开页面验证。另外要检查 Actions 是否真的触发了只有推送到main分支并且工作流文件存在于 main 分支时才会自动执行。如果你是在其他分支推送的Actions 不会运行。7.4 Codex 接入模型服务时报错如果你不是使用官方默认配置而是接了第三方模型服务有时会看到类似下面这类报错提示某个模型名不被支持。提示返回结果格式不符合 Codex 预期。提示思考模式下缺少某个必须字段服务端返回 HTTP 400。这类问题的根因通常不是 Codex 本身坏了而是模型名称、接口格式或请求参数与服务商要求不一致。排查思路如下确认填写的模型名称与模型服务商实际提供的名称完全一致。确认接口地址是否填对不要出现多余空格或末尾斜杠。确认是否开启了思考模式如果服务商要求回传reasoning_content字段而本地版本不支持可以考虑关闭思考模式或升级 Codex 到支持该字段的版本。查看 Codex 日志或终端输出找到真实的upstream_status和cause字段它们会直接告诉你是哪一步请求失败了。需要注意不同模型服务商的能力差异很大有的模型支持思考模式有的不支持支持思考模式的模型对请求格式的要求也可能不同。建议先按服务商提供的官方示例跑通一次再切换 Codex 默认模型这样能更快定位问题。7.5 上下文窗口溢出如果你在同一个 Codex 会话里持续开发很久可能会看到类似 “ran out of room in the models context window” 的提示。这说明当前会话累积的上下文已经超出了模型的窗口上限。解决方案很直接新开一个会话或者在重新开始时只描述当前需要修改的问题不要重复粘贴大量历史代码。Codex 读取项目文件的方式和聊天粘贴不同它通常只会读取它认为需要的文件所以尽量避免在对话里堆叠大段代码让 Codex 自己去读文件会更省上下文。7.6 想绑定自定义域名想让网站不使用用户名.github.io而用自己的域名可以在仓库 Settings - Pages 中找到 “Custom domain”填入你的域名然后在 DNS 服务商处添加一条解析记录。绑定后 GitHub 会自动签发 HTTPS 证书证书生效需要等待几分钟到几十分钟不等。需要注意如果使用自己的域名并且仓库不是用户名.github.io同样要注意子路径和资源路径的问题。8. 最佳实践与工程建议到这里整条自动化部署链路已经跑通了。最后分享一些我在实际使用中觉得重要的工程化建议能帮你把这个方案用得更稳、更省心。8.1 仓库目录与提交规范保持仓库目录整洁工作流配置文件放在.github/workflows/下源码按项目结构组织不要把构建产物dist/提交到仓库里。可以在项目根目录创建.gitignore文件node_modules/ dist/ .DS_Store提交信息建议使用清晰的约定式风格例如feat: 新增项目展示区域 fix: 修复移动端导航栏错位 ci: 更新部署工作流这样的好处是以后想查“哪次改动导致问题”直接看提交历史就能定位。8.2 静态资源路径与版本管理无论使用哪种前端方案资源路径问题都是 GitHub Pages 子路径部署的头号坑。如果你用 Vite记得配置 base如果你写纯 HTML尽量使用相对路径。另外如果你的网站引用了大量图片、字体建议把文件放在统一目录里比如assets/并且用语义化文件名。大型文件要压缩后再提交避免仓库体积膨胀和页面加载缓慢。8.3 缓存、安全与隐私边界GitHub Pages 自带缓存线上更新不会立即生效这既是优点也是坑。建议在页面里给静态资源加版本号例如style.css?v2这样修改样式后浏览器会重新加载文件。安全方面要特别注意GitHub Pages 是公开站点任何人都能访问如果你创建的是公开仓库代码也会被所有人看到。绝对不要把 API Key、数据库密码、私钥等敏感信息提交到仓库里。Codex 在生成代码时如果涉及配置项也最好用环境变量或单独的管理方式不要硬编码在源码中。8.4 用 Codex 持续迭代的个人工作流当网站上线后你的日常迭代流程可以简化为在本地启动 Codex 会话描述要修改的内容。Codex 修改代码进行本地预览调整样式和交互。检查无误后提交 Git推送 main 分支。打开 GitHub Actions 页面确认部署成功。刷新线上地址验证更新效果。如果改了没什么把握的样式或功能建议先本地预览确认再推送到线上。虽然 Actions 部署很快但线上环境毕竟会暴露给访问者没必要让访问者替你测试。9. 总结与下一步学习建议这套流程的核心其实不是某个单一工具而是把 AI 编程、Git 版本管理、自动化部署三个能力组合起来形成一个完整的个人网站发布闭环。Codex 帮你省掉重复编码的时间和精力Git 帮你记录每个历史版本GitHub Actions 帮你把发布从手动操作变成自动行为GitHub Pages 则负责免费稳定地把网站呈现给全世界。如果你也卡在“本地能访问、别人访问不了”和“每次更新都要手动上传”这两个问题上建议先按文章里的基础案例完整跑一遍。不要一上来就追求复杂的设计和框架先用纯 HTML 页面打通整条链路再逐步引入构建工具、自定义域名、更多页面结构。下一步可以继续学习 Git 分支工作流、前端构建工具、GitHub Actions 的更多触发方式也可以研究如何给网站添加访问统计、SEO 标签和社交媒体分享卡片。等你把基础流程熟练之后再回头用 Codex 迭代网站体验会顺畅很多。