先解决两个最扎心的问题用 Codex 开发出来的网站为什么别人访问不到为什么每次改完需求还得手动上传一次文件答案很简单——本地开发服务器只在你电脑上跑别人当然进不来而手动上传的本质是缺少一条从代码仓库到线上环境的自动发布链路。这次我们就用 Codex GitHub Pages 搭一条免费、高效、可重复的发布流程把这套问题一次性解决。这个方案的核心只有三件事Codex 负责写代码和改需求Git 负责记录迭代GitHub Pages 负责把网站免费托管到公网。整条链路不需要买服务器、不需要配域名、不需要维护数据库适合个人博客、作品集、项目展示页、工具站这类静态网站。本文会从环境准备讲起带你完成 Codex 安装、网站生成、仓库推送、Pages 开启、Actions 自动部署最后给出这套流程里最常见的报错排查清单。1. Codex GitHub Pages 核心能力速览能力项说明项目类型AI 编程工具 Codex 与静态托管平台 GitHub Pages 的联合部署方案主要功能用自然语言生成网站代码、自动迭代修改、免费部署到公网托管成本GitHub Pages 对公开仓库免费托管静态网站无需购买服务器前端能力支持 HTML / CSS / JavaScript / 静态站点生成器等纯静态内容后端能力不支持服务端运行、数据库、用户登录等动态功能部署方式Git 推送 GitHub Actions 自动部署支持手动触发和定时触发使用门槛需要 GitHub 账号、本地安装 Codex CLI、掌握基础 Git 命令适合场景个人简历页、产品介绍页、博客、文档站、开源项目主页合规要求网站内容、素材、字体、图片必须有合法授权不得侵权从材料看Codex 目前有 CLI、桌面端、VS Code 插件、云端等多种使用形态常见做法是安装 Codex CLI 后在终端里直接对话也可以配合 VS Code 或第三方模型服务一起用。更稳妥的判断是先跑通最简单的 CLI 流程再根据需求接编辑器插件和自动化部署不要一开始就把工具链搞得太复杂。2. 这个方案解决什么问题使用边界在哪这套方案解决的核心痛点是开发完成不是终点能被访问才是终点。第一个痛点是本地访问限制。你用 Codex 在本地生成并运行了一个网站http://localhost:3000只能在本机打开同事、朋友、客户都访问不到。要解决这个问题必须把静态文件托管到一个公网可达的地址GitHub Pages 就是免费且稳定的选择。第二个痛点是迭代发布效率低。很多人的工作流是这样的Codex 改完代码手动执行构建然后把 dist 文件打包传到某个服务器或对象存储传错了还要重新来。一旦需求变多每次手动上传至少浪费几分钟还会因为漏传文件导致线上页面样式错乱。用 Git 管理版本、用 GitHub Actions 自动部署后每次只需要提交代码线上站点会在几分钟内自动更新。但也要清楚这个方案的边界。GitHub Pages 只能托管静态文件凡是需要服务端运行、数据库存储、登录鉴权、支付回调、动态渲染的后端能力它都做不了。如果网站需要表单提交后端的存储逻辑需要单独部署 API 服务Pages 只负责前端展示。另外国内访问 GitHub 和 GitHub Pages 的稳定性受网络环境影响正式商用场景建议评估备选方案。合规边界同样要重视。Codex 生成的代码、你写入的文案、页面里引用的图片和字体都必须拥有合法使用权。涉及他人肖像、商标、版权素材的内容未授权不要上线。GitHub 公开仓库意味着站点代码默认公开可见不要把密钥、Token、数据库连接串这类敏感信息提交进去。3. 环境准备与前置条件3.1 需要准备的账号开始操作前先准备一个 GitHub 账号。如果还没有先到 GitHub 官网注册并完成邮箱验证。GitHub Pages 的站点地址默认是用户名.github.io所以用户名会直接出现在你的网站 URL 里注册时选一个简洁、正式的名字会更利于后续推广。如果希望把 Codex 接入第三方模型服务还需要准备对应服务商的 API Key。网络材料里能看到一些常见接入方式比如通过 CC Switch 这类客户端切换 Codex 的模型供应商让 Codex 支持 DeepSeek 等模型。具体可用性会随版本变化接入前先到对应服务商页面确认当前支持的模型和鉴权方式。3.2 安装 Codex CLICodex CLI 是 OpenAI 官方提供的命令行编程智能体可以在终端里读取项目代码、生成文件、执行 Git 操作和运行命令。安装前先确认本机有 Node.js 环境建议使用较新的 LTS 版本。打开终端执行npm install -g openai/codex如果网络环境安装 npm 包比较慢可以临时切换到国内 npm 镜像npm config set registry https://registry.npmmirror.com npm install -g openai/codex安装完成后验证版本codex --version首次使用 Codex 需要登录 OpenAI 账号或配置 API Key。不同版本配置方式不同常见做法是通过环境变量指定 API Keyexport OPENAI_API_KEY你的API Key如果接入了第三方模型网关Codex 的模型提供商配置通常会走config.toml或环境变量具体以 Codex 当前版本的官方文档为准。网络材料里出现过codex cli、codex 桌面版、vscode codex、idea集成codex等关键词说明 Codex 已经覆盖了命令行、桌面端和主流编辑器先用 CLI 跑通再扩展其他入口比较稳妥。3.3 初始化本地 Git 环境GitHub Pages 的正常工作流建立在 Git 之上所以本机必须安装 Git。检查是否已安装git --version如果没安装根据操作系统选择对应方式Windows 下载 Git for WindowsmacOS 用brew install gitLinux 用系统包管理器安装。安装后配置用户名和邮箱提交记录会用到git config --global user.name 你的用户名 git config --global user.email 你的邮箱到这里前置环境就齐了GitHub 账号、Node.js、Codex CLI、Git。下一节开始用 Codex 生成网站。4. 用 Codex 从零生成个人网站4.1 初始化项目目录先为网站创建一个独立目录并进入目录mkdir my-website cd my-website如果你已经用 Codex 在别的目录写过网站可以直接跳到第 5 节。如果是从零开始建议先让 Codex 生成一个最小可运行站点把链路跑通后再增加功能。在项目目录中启动 CodexcodexCodex 会进入交互式对话界面。此时输入需求例如帮我创建一个个人网站首页包含顶部导航、个人简介、作品展示、联系方式四个区块。使用纯 HTML CSS JavaScript不需要构建工具代码放到当前目录下并保证文件结构清晰。Codex 会生成对应的 HTML、CSS、JavaScript 文件。不要急着直接部署先检查生成的文件结构ls -la按常理你会看到类似index.html、styles.css、script.js这样的文件。如果 Codex 帮你初始化了 Git 仓库执行git status能看到未提交的改动。4.2 本地预览网站静态站点可以在本地直接预览。如果项目是纯 HTML/CSS用 Python 自带的服务即可python3 -m http.server 8080如果系统里没有 Python可以改用 Node.js 的npx servenpx serve .浏览器访问http://localhost:8080查看页面是否能正常显示。这里重点确认三件事页面标题是否正确、样式是否加载、图片资源是否能显示。如果资源文件有路径问题先让 Codex 修复再继续后续部署。4.3 让 Codex 完善内容首版页面往往比较粗糙可以继续在 Codex 对话里提需求。比如作品展示区块目前只有占位图请替换为三个真实项目卡片每个卡片包含项目名称、一句话简介、技术标签和跳转链接。每次修改后都回到浏览器刷新检查。这个阶段的核心原则是小步快跑一次只让 Codex 改一个功能改完立即验证避免一次对话塞入太多需求导致页面结构混乱。4.4 提交首批代码网站初步可用后先把代码提交到本地 Git 仓库git init git add . git commit -m feat: 初始化个人网站如果 Codex 已经帮你初始化过仓库跳过git init直接 add 和 commit 即可。5. 部署到 GitHub Pages让别人能访问5.1 创建 GitHub 仓库登录 GitHub点击右上角加号选择 New repository。仓库名称可以是你的用户名.github.io这是 GitHub Pages 的默认站点仓库也可以是任意名称比如my-website这种情况下站点地址会变成https://用户名.github.io/仓库名/。建议先使用用户名.github.io命名部署后访问地址最简洁。创建时注意两点仓库建议设置为 Public因为 GitHub Pages 免费托管公开仓库不要勾选Add a README file等初始化文件避免和本地仓库产生冲突。5.2 推送代码到 GitHub仓库创建完成后GitHub 会给出远程地址。在本地项目目录中执行git remote add origin https://github.com/你的用户名/你的仓库名.git git branch -M main git push -u origin main推送时需要输入 GitHub 用户名和密码。现在的密码字段需要使用 Personal Access TokenPAT不再支持账号密码直接登录。创建 PAT 的路径是GitHub 头像 → Settings → Developer settings → Personal access tokens → Tokens (classic)勾选repo权限后生成复制保存。5.3 开启 GitHub Pages进入仓库页面点击 Settings → Pages在 Build and deployment 区域设置 Source对于用户名.github.io仓库Source 选择Deploy from a branchBranch 选择main路径选/ (root)点击 Save。对于普通仓库如果希望用 GitHub Actions 自动部署Source 可以选GitHub Actions具体配置见下一节。稍等一两分钟Settings → Pages 页面顶部会出现站点地址。打开https://用户名.github.io此时网站已经公网可访问了。把链接发给你朋友对方不需要任何本地环境直接就能打开。5.4 验证访问部署成功的判断标准很简单浏览器无痕窗口打开 GitHub Pages 地址页面能正常渲染样式和资源没有 404。如果首页显示出来了说明 Codex 写的代码本身没问题发布链路也通了。如果打开是 404优先检查三件事仓库是否 Public、分支名是否是main、文件是否有index.html在根目录。GitHub Pages 默认加载根目录下的index.html如果入口文件名不对页面就会 404。到这里最核心的别人能访问已经解决。但目前的流程还是手动的每次 Codex 改完代码都要本地 commit、push再去 GitHub Pages 设置页刷新。下一步用 GitHub Actions 把发布自动掉。6. 自动化迭代提交一次自动上线6.1 自动化思路GitHub Actions 是 GitHub 自带的 CI/CD 服务。它的用途可以理解为只要仓库收到代码推送就自动执行一段构建和部署脚本把最新的静态文件发布到 GitHub Pages。这样 Codex 每次改完需求我们只需要git push剩下的事全部交给 Actions。这套流程对每次迭代都是手动上传的问题非常对症。手动上传的痛点在于要自己构建、自己找上传目录、自己清理旧文件、还要担心漏传。改成 Actions 后构建和上传都固化成了流水线不存在这版忘了传某个文件的问题。6.2 编写 workflow 配置文件在项目根目录创建.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: deploy: 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这个配置适合纯静态站点直接把整个仓库作为站点内容发布。如果 Codex 的项目需要构建比如使用了 Vite、Next.js 静态导出等工具需要在 Upload artifact 之前增加构建步骤- name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm install - name: Build run: npm run build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: ./dist注意path要改为构建产物的实际输出目录。不同框架的产物目录不一样Vite 默认是dist其他框架需要按实际配置调整。6.3 开启 Actions 部署源写好 workflow 后回到 GitHub 仓库的 Settings → Pages把 Source 切换为GitHub Actions。这样 Pages 会直接接受 Actions 部署产物不再监听分支文件变化。本地提交 workflow 并推送git add . git commit -m ci: 添加 GitHub Pages 自动部署 git push推送后进入仓库的 Actions 标签页能看到名为Deploy to GitHub Pages的 workflow 开始运行。第一次运行大约需要 1 到 3 分钟运行完成后刷新 GitHub Pages 地址线上站点就是最新版本了。6.4 完整迭代闭环现在整个迭代闭环是这样的本地启动 Codex提出新需求。Codex 修改代码用户本地刷新验证。确认无误后执行git add . git commit -m 修改说明 git push。GitHub Actions 自动构建并发布。几分钟后线上站点自动更新无需手动上传。这个流程跑顺之后手动上传这个动作就彻底消失了。无论 Codex 改了多少次页面、新增了多少文件只要 push 到 main 分支线上就会同步更新。7. Codex 常见报错与排查日常使用 Codex 开发网站时难免会遇到报错。下面这组问题是网络材料里出现过的类型整理成排查表供参考。问题现象可能原因排查方式解决方案提示cc switch local proxy failed while handling codex endpoint /responses第三方模型网关代理配置异常或本地代理服务未正常启动检查 CC Switch 的代理地址、端口、模型选择查看 Codex 使用的模型是否被当前服务商支持重启代理客户端重新选择模型并保存确认 local proxy 地址与 Codex 配置一致必要时切换到直连模式测试提示the gpt-5.6-sol model is not supported when using codex with ...Codex 配置文件中指定的模型在当前网关或账号下不可用查看 Codex 当前模型配置对比服务商支持的模型列表在 Codex 配置中切换到可用模型比如 DeepSeek 系列或官方模型不要使用不存在的模型名提示models context window相关错误对话上下文太长超过了模型上下文窗口限制检查当前对话历史是否包含大量旧代码输出新开一个 Codex 线程把关键需求重新描述或把大文件拆成小任务逐步处理Codex 生成了代码但本地预览空白JS 文件存在浏览器兼容问题或资源路径错误打开浏览器开发者工具查看 Console 和 Network 报错让 Codex 根据报错信息修复检查资源文件引用路径是否为相对路径codex命令不存在Node.js 未安装或全局 bin 目录不在 PATH 中执行node -v确认 Node 环境检查 npm 全局目录重新安装 Node.js或把 npm 全局目录加入 PATHAPI Key 鉴权失败环境变量未配置或 Key 已失效执行echo $OPENAI_API_KEY检查环境变量重新导出环境变量或重新生成 API Key关键在于Codex 的报错大多和模型配置与上下文长度有关。用第三方网关时先确认模型在供应商侧是否可用对话次数太多时果断新开线程不要让旧代码占用上下文空间。8. GitHub Pages 常见问题与排查问题现象可能原因排查方式解决方案打开 Pages 地址 404仓库不是 Public或根目录没有 index.html或分支名不是 main检查仓库可见性、文件结构、分支名将仓库改为 Public确认入口为 index.html分支切到 main页面样式丢失CSS 文件使用绝对路径如/styles.css在仓库子路径下失效查看 Network 面板中 CSS 请求状态将资源引用改为相对路径或不使用子路径部署推送代码后线上不变GitHub Pages 未用 Actions 部署且 Source 仍监听旧分支查看 Actions 标签页是否有运行记录按 6.2 节配置 workflow并在 Pages 设置里切换 Source 为 GitHub ActionsActions 运行失败workflow 语法错误或构建命令失败点击 Actions 中失败的 run查看具体步骤日志根据日志修复 work flow 或构建命令修正产物目录路径上传时提示权限不足远程路径写错或使用密码而非 PAT检查 remote 地址重新生成 PAT使用 PAT 作为密码远程地址改成自己的用户名和仓库名自定义域名不生效DNS 解析未配置或 CNAME 文件缺失在 Settings → Pages 查看 Custom domain 状态按 GitHub 提示配置 DNS 记录在仓库根目录添加 CNAME 文件9. 最佳实践与合规建议9.1 目录与文件规范部署前整理好项目结构。推荐保持最小化my-website/ ├── index.html ├── styles/ │ └── main.css ├── scripts/ │ └── main.js ├── images/ │ └── logo.png └── .github/ └── workflows/ └── deploy.yml不要把所有代码塞在一个 HTML 文件里也不要把 node_modules 等大型依赖目录提交进仓库。可以在项目根目录添加.gitignore文件忽略不需要提交的目录node_modules/ dist/ .DS_Store *.log9.2 内容安全与授权Codex 生成的网站内容不代表可以任意使用。页面用到的图片、图标、字体、文案、品牌标识都需要确认授权。推荐使用 Unsplash、Pexels 等免费图库或自己拍摄、绘制的素材。涉及他人肖像、声音、作品的内容必须先获得授权再发布否则可能面临侵权风险。同时Codex 可能在生成代码时参考了训练数据中的样本虽然这属于正常的编码辅助但发布前建议人工复核页面中的文案和样式确保没有搬运他人受版权保护的内容。9.3 敏感信息管理GitHub 公开仓库会把所有代码暴露在公网。不要把 API Key、数据库密码、Token、内网地址、个人敏感信息写进代码或提交到仓库。Codex 对话中也不应该传入密钥。如果误提交了敏感信息立刻删除并不能保证历史记录被清除更稳妥的做法是作废并重新生成密钥。9.4 小步提交避免大改用 Codex 迭代网站时建议每个功能单独提交一次commit 信息写清楚变更内容。例如git commit -m feat: 添加作品展示卡片 git commit -m fix: 修复移动端导航栏遮挡问题这样出问题时可以快速回退到上一个可用版本。Codex 修改代码后一定要先在本地预览确认没有明显问题再 push避免把坏版本发布到线上。9.5 定时验证线上地址GitHub Pages 不会每天提醒你站点是否正常。建议在关键时间节点比如每周或每月大版本更新后用无痕窗口检查线上页面。如果开启了自定义域名还要留意 HTTPS 证书状态。10. 总结这个解决方案最值得尝试的点在于用最少的基础设施成本打通了一条代码到公网的完整链路。Codex 负责把需求变成代码GitHub Pages 负责让网站免费可访问GitHub Actions 负责把每次迭代自动化三者组合起来个人网站从开发到上线的成本被压到了极低。第一次尝试时建议先做一个最简单的单页简历把Codex 生成 → git push → Pages 打开这条主链路跑通跑通之后再考虑接入 Actions 自动部署、自定义域名、博客系统、更多页面。最容易踩的坑集中在两个地方一是第三方模型网关配置导致的 Codex 报错遇到这类问题优先检查模型名和代理地址二是 GitHub Pages 的 Source 配置如果线上一直不更新先确认发布源是不是已经切到了 GitHub Actions。后续可以继续扩展的方向包括用 Vite 或 Astro 改造为现代前端项目、接入自定义域名、给网站加访问统计、利用 GitHub Actions 做每日自动构建。需要后端能力时可以在 Pages 前端之外单独部署服务器把 API 地址通过环境变量注入页面。这套流程的可复制性很强换成其他静态站点生成器思路完全一致。建议收藏备用等你把 Codex 和 Git 的配合用熟后会发现发布网站真的不需要再手动上传了。