最近用 Codex 做了一个个人网站本地预览一切正常但发给朋友看时对方却怎么也打不开每次改完文案又得重新压缩、上传、覆盖来回折腾非常浪费时间。如果你也遇到过类似场景这篇教程应该能帮你省掉不少力气。我会完整演示如何用 Codex 生成一个静态网站再通过 GitHub Pages 把网站免费部署到公网最后借助 GitHub Actions 把“每次手动上传”变成“推送代码后自动发布”。1. 背景与核心概念在动手之前先花几分钟把几个关键概念讲清楚。只有理解了它们各自负责什么后续配置过程中遇到报错时才知道该往哪个方向排查。1.1 为什么你的网站别人进不去很多初学者用 Codex 开发完网站后发现别人访问不了根本原因通常只有一个网站只运行在你自己电脑上。Codex 帮你在本地启动了一个服务地址往往是http://localhost:3000或http://127.0.0.1:8080。localhost的意思是“本机回环地址”它只代表你当前这台电脑。朋友、同事、网上的陌生人访问这个地址时指向的是他们自己的电脑自然什么都看不到。想要让别人也访问到必须做一次“部署”在服务器上准备一个可访问的静态目录把你的 HTML、CSS、JS 文件上传上去通过一个公网地址对外提供服务。GitHub Pages 就是帮你完成这整套流程的免费方案而且不需要自己买服务器、装 Nginx、配域名。1.2 Codex 是什么Codex 是 OpenAI 推出的 AI 编程代理工具官方名称叫 Codex CLI后来也提供了桌面版和 IDE 插件。它的核心是“代理式”编程你给它一个任务描述它不只是补全一段代码而是会自己分析问题、列出计划、修改多个文件、执行命令、查看运行结果然后继续迭代直到任务完成。相比传统的“在聊天窗口里复制代码再粘贴”Codex 更接近一个“能读懂你项目目录的 AI 开发助手”。你可以直接对它说把当前项目改成响应式布局顺便修复导航栏在移动端不显示的问题它会读取项目文件、修改对应代码、运行验证并告诉你改了什么。1.3 GitHub Pages 是什么GitHub Pages 是 GitHub 提供的静态网站托管服务它可以把仓库里的静态文件直接变成一个可访问的网站。它的典型特点包括免费不需要单独付费自动构建支持 Jekyll也能配合 GitHub Actions 构建前端项目稳定静态资源走 CDN访问速度在多数地区都不错上线快开启后几分钟内就能通过https://用户名.github.io访问。它适合个人主页、项目介绍站、产品落地页、技术文档站、简历页等纯前端网站。如果你的网站只有 HTML、CSS、JS没有后端服务那 GitHub Pages 是非常理想的托管方案。1.4 适用场景与边界用 Codex GitHub Pages 组合最舒服的场景是场景是否适合个人简介主页非常适合项目展示页 / 落地页非常适合前端框架静态站点Vite、React、Vue 打包后适合配合 Actions 自动化技术文档 / 博客适合可配合 Jekyll 或静态博客生成器需要后端接口的业务系统不适合Pages 只托管静态文件需要注册登录、数据库写入的网站不适合需要额外的后端服务需要按请求计费或被高频访问的接口服务不适合简单来说纯前端、内容型页面强烈推荐动态业务系统请老老实实买服务器。2. 环境准备与前置条件开始前需要先把环境准备齐全。下面这些工具和账号是必需的缺一个都会中途卡住。2.1 准备工作清单项目说明GitHub 账号用于创建仓库和开启 PagesGit用于本地提交代码并推送到远程仓库Node.jsCodex CLI 基于 Node.js 安装运行Codex CLI 或桌面版AI 编程工具本文以 CLI 为例浏览器用于本地预览和访问线上域名版本说明具体版本更新较快本文不写死某个版本号。Node.js 建议使用官方 LTS 版本Codex 建议通过官方文档安装最新版本。如果你已经装有旧版本优先升级到最新版避免因为版本过旧导致指令无法识别。2.2 安装 Git 与 Node.jsGit 的安装不做特殊介绍Windows 用户直接下载安装包macOS 用户如果装了 Homebrew可以执行brew install git安装完成后确认版本git --versionNode.js 可以直接从官网下载 LTS 安装包安装完成后确认node -v npm -v出现版本号即说明安装成功。3. Codex 安装、登录与基础使用Codex 是这篇文章的“生产力核心”。这部分我会完整演示安装、登录以及如何用 Codex 生成一个小型个人网站。3.1 安装 Codex CLICodex CLI 的官方包名是openai/codex通过 npm 全局安装即可npm install -g openai/codex安装完成后执行codex --version能打印出版本号说明安装成功。如果你更习惯图形界面也可以直接从 OpenAI 官网下载 Codex 桌面版或者在 VS Code 插件市场搜索 Codex。后面步骤里我用 CLI 操作桌面版的操作逻辑是一样的只是交互方式不同。3.2 登录 Codex安装好之后第一次使用需要登录认证。在终端运行codex login命令执行后浏览器会弹出登录页面完成账号授权后回到终端会看到登录成功的提示。如果你的网络环境无法直接访问官方接口或者你使用的是第三方兼容接口需要在 Codex 的配置文件中调整base_url、模型名称等参数。注意不同兼容网关的参数格式不完全一样建议以你使用的服务商文档为准。常见做法是在配置里指定model 你的模型名 model_provider 你的服务商标识这里的配置思路是通用的Codex 本身只是一个客户端真正响应任务的是模型接口。只要接口协议兼容Codex 就能正常工作。不过这一步不是必须的如果你能正常访问官方接口跳过这里即可。3.3 使用 Codex 生成个人网站先在本地创建一个项目目录mkdir my-site cd my-site接下来启动 Codex让它帮我们在当前目录生成一个完整的静态网站。在终端执行codex进入交互界面后输入你的需求。我用的提示词参考如下请在当前目录下创建一个个人网站项目要求 1. 使用纯 HTML、CSS、JavaScript不使用框架 2. 包含首页 index.html、样式文件 style.css、脚本文件 script.js 3. 页面包含三个区块自我介绍、项目展示、联系方式 4. 风格简洁现代适合个人开发者展示 5. 样式使用响应式布局手机端也能正常查看 6. 所有资源文件使用相对路径方便部署到 GitHub Pages。Codex 会先列出实施计划然后逐个创建文件。任务执行过程中它会读取目录内容、生成文件、必要时运行命令验证。完成后你会看到my-site目录下出现了几个文件my-site/ ├── index.html ├── style.css ├── script.js └── README.md这一步的核心价值在于你不用手动从零写页面代码Codex 根据自然语言需求把项目骨架搭好了。下面是一个简单版的index.html示例方便你理解生成结果大概长什么样。实际生成的内容可能更丰富!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title我的个人网站/title link relstylesheet hrefstyle.css / /head body header h1你好我是示例博主/h1 p一个喜欢折腾代码的开发者/p /header section idabout h2关于我/h2 p这里可以放自我介绍比如技术方向、工作经历、兴趣爱好。/p /section section idprojects h2项目展示/h2 ul li项目一Codex 实战教程/li li项目二GitHub Pages 自动部署/li /ul /section section idcontact h2联系方式/h2 p邮箱exampleexample.com/p /section script srcscript.js/script /body /html这里需要特别提醒提示词里一定要加上“使用相对路径”这一条。如果生成的代码里写的是/style.css这种绝对根路径在 GitHub Pages 项目页地址形式为https://用户名.github.io/仓库名/下会出现样式加载不到的问题。这是一个很典型的部署坑。4. 本地预览与验证网站代码生成后不要急着推送到 GitHub先在本地跑一遍确认页面和功能都正常。4.1 本地启动静态服务在项目目录下执行python3 -m http.server 8000如果你没装 Python也可以用 npx 启动一个静态服务npx serve .然后浏览器访问http://localhost:8000如果页面正常显示说明静态资源路径没有问题。4.2 检查文件结构用ls或资源管理器确认目录结构是否是预期结果。如果项目里生成了类似node_modules的目录推送前要排除掉这些文件不需要进仓库。如果你是第一次接触 Git 和 GitHub建议在执行推送命令前先配置用户名和邮箱git config --global user.name 你的用户名 git config --global user.email 你的邮箱4.3 本地预览时的常见错误错误现象原因解决办法页面白屏JS 报错或资源路径错误打开浏览器开发者工具的 Console 查看报错样式不生效CSS 路径写错检查link标签的href是相对路径还是绝对路径点击按钮无反应脚本加载失败检查script标签的src确认文件存在于指定路径这一步是整个流程里成本最低的检测环节。本地验证通过再进入部署阶段能帮你避免在线上反复调试。5. 推送到 GitHub 并开启 GitHub Pages代码在本地跑通后下一步就是把项目推送到 GitHub然后开启 Pages 服务。这也是解决“别人访问不了”的关键一步。5.1 创建 GitHub 仓库登录 GitHub点击右上角“”号选择“New repository”。仓库命名有一个小技巧如果你想得到一个https://用户名.github.io的主站点地址仓库名必须叫用户名.github.io。你注册 GitHub 时给自己起的名字如果是zhangsan那么仓库名就是zhangsan.github.io这样开启 Pages 后访问地址就是https://zhangsan.github.io如果仓库名是其他名字比如my-site那么访问地址是https://zhangsan.github.io/my-site/创建仓库时如果你想省事可以不勾选“Add a README file”因为本地项目已经有文件了。请注意免费版 GitHub 上公开仓库才能使用 GitHub Pages。可以先把仓库设为 Public。5.2 推送代码到远程仓库在本地项目目录执行以下命令git init git add . git commit -m Initial commit: personal website git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main推送提示失败时先检查远程地址是否写错GitHub 账号是否已完成 SSH 或 HTTPS 认证仓库是否已经存在同名文件导致冲突。5.3 开启 GitHub Pages进入仓库页面点击Settings在左侧菜单找到Pages。在Build and deployment区域Source 选择Deploy from a branchBranch 选择main目录选择/ (root)点击 Save。等待一两分钟后刷新页面会出现一行提示Your site is live at https://你的用户名.github.io/你的仓库名/打开这个地址你会看到和本地一模一样的页面。把链接发给任何人对方都能直接访问。到这里“开发完网站别人不能访问”的问题就解决了。但还有一个痛点没解决每次改完代码都要手动上传吗6. 让“手动上传”变成“自动发布”很多同学发布网站的流程是修改代码git push手动去 GitHub 重新构建等页面更新。如果只做一次还好每周迭代一次就非常痛苦。更严重的是有时候忘了重新构建线上内容还是旧的。解决办法就是GitHub Actions 自动部署。6.1 自动化部署原理GitHub Actions 是 GitHub 提供的持续集成/持续部署CI/CD服务。你可以把它理解成“在 GitHub 服务器上运行的自动化脚本”。我们只需要在仓库中放置一个工作流配置文件以后只要你把代码推送到指定分支GitHub 就会自动执行部署流程。所以完整流程变成本地修改代码 ↓ git add . git commit -m 更新内容 ↓ git push ↓ GitHub Actions 自动构建并部署 ↓ 线上页面自动更新6.2 编写 GitHub Actions 工作流在项目根目录创建.github/workflows/deploy.yml目录和文件name: Deploy to GitHub Pages on: push: branches: [ main ] permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup GitHub Pages uses: actions/configure-pagesv4 - 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 的权限Upload artifact步骤把当前目录下的所有文件上传为部署产物Deploy to GitHub Pages步骤完成实际的发布动作。如果你的项目是用 Vite、React、Vue 这类前端框架构建的需要先安装依赖并打包再上传打包目录工作流会多两步- name: Install dependencies run: npm install - name: Build run: npm run build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: dist对于本文的纯静态网站来说不需要构建步骤直接把当前目录上传即可。配置好后把文件推送到 GitHubgit add . git commit -m Add GitHub Actions deploy workflow git push然后打开仓库的Actions标签页可以看到工作流正在运行。运行结束后Pages 设置里如果 Sources 还没改可以把它改成GitHub Actions模式这样后续发布就完全交给工作流处理了。以后再修改网站内容只需要git add . git commit -m 更新项目介绍 git push等一两分钟线上页面自动更新。这就是“自动发布”的完整落地。7. 常见问题与排查思路整理几个最常见的坑按现象、原因、解决方法列出来遇到问题可以对照排查。问题现象常见原因解决思路访问域名显示 404Pages 没有开启或分支/目录选错检查 Settings → Pages 的 Source 和 Branch 配置页面显示但没有样式资源路径使用了绝对路径把所有href、src改成相对路径推送代码后页面不更新没有配置 Actions或 Actions 运行失败查看 Actions 日志确认部署流程是否执行成功git push失败远程仓库有本地没有的提交先git pull --rebase再重新推送Codex 命令提示找不到Node.js 未安装或全局路径未配置重新安装 Node.js确认 npm 全局目录在 PATH 中Codex 登录后报认证失败登录凭证过期或网络异常重新执行codex login检查接口地址配置使用第三方模型时接口返回 400提示reasoning_content相关错误某些模型在思考模式下要求把reasoning_content原样传回查阅你的兼容网关文档调整参数透传方式或关闭思考模式其中最后一个问题如果你使用的是社区兼容网关或第三方模型接口确实比较常见。不同的网关对reasoning_content的处理策略不一样解决思路主要是看网关文档以及在 Codex 配置里调整对应的模型参数。这部分没有统一答案关键是先看错误信息里提示的是哪个字段。8. 最佳实践与工程建议8.2 仓库与分支管理建议仓库名直接采用用户名.github.io这样线上地址最短、最好记也方便后续绑定自定义域名。主分支使用main。Actions 工作流默认监听main分支名不一致会导致自动化不触发。每次提交信息写清楚“改了什么”比如更新项目列表、修复移动端样式不要写update、test这种无意义提交。8.2 资源与构建产物管理所有资源路径使用相对路径不要写/style.css这种根路径使用 Git 忽略文件.gitignore把不需要入库的内容排除掉例如node_modules/ .DS_Store dist/ .env如果使用前端框架不要让dist、build这类打包产物直接入库应该由 Actions 在服务器上构建。8.3 安全边界不要把 API Key、Token、数据库连接串提交到仓库。即使是私有仓库也不建议保存真实密钥因为密钥一旦进入 Git 历史很难彻底清除GitHub Pages 是公开站点任何上传到静态目录的文件都可能被访问。不要往网站目录里放后台配置、备份文件、内网地址等信息如果后续要使用自定义域名在仓库 Settings → Pages 里配置 Custom domain并在域名服务商处添加 CNAME 记录指向用户名.github.io。8.4 自动化流程建议第一次配置 Actions 时先故意修改一个小文件并推送观察整个流程是否能跑通Pages 设置里 Sources 选择GitHub Actions后后续发布完全由 Actions 管理不要再手动选择分支部署两者不要混用否则容易产生“不知道哪个生效”的困惑本地提交前先git status确认没有多余文件尤其是.env、node_modules。8.5 使用 Codex 的小技巧需求描述越具体生成结果越接近预期。让 Codex “做一个网站”太宽泛建议说明技术栈、页面区块、风格方向同一项目反复使用 Codex 时把项目背景写在一个README.md里Codex 读取后能更好地理解项目上下文Codex 生成代码后仍然需要自己读一遍核心代码特别是涉及上传、删除、执行命令这类操作时要确认它不会执行危险命令。9. 结语与下一步建议到这里你已经掌握了三条核心技能用 Codex 快速生成静态网站用 GitHub Pages 免费把网站部署到公网用 GitHub Actions 实现推送代码后自动发布。如果你按照上面的步骤操作现在应该拥有一个可以分享给任何人的线上地址并且每次改完内容只需要git push就能完成发布。建议你接下来做三件事把网站的自我介绍改成自己的真实信息顺便练习一次“修改 → 推送 → 自动更新”的完整流程如果网站是纯静态页面可以继续尝试接入一个前端框架比如 Vite Vue 或 React然后修改 Actions 工作流加入构建步骤用 Codex 给网站加一些更复杂的功能比如项目筛选、动画效果、暗黑模式把这个免费托管的个人网站当成长期迭代的试验场。如果这篇文章对你有帮助可以收藏备用如果在操作中遇到其他问题也欢迎把报错信息留在评论区一起讨论排错思路。
最近用 Codex 做了一个个人网站本地预览一切正常但发给朋友看时对方却怎么也打不开每次改完文案又得重新压缩、上传、覆盖来回折腾非常浪费时间。如果你也遇到过类似场景这篇教程应该能帮你省掉不少力气。我会完整演示如何用 Codex 生成一个静态网站再通过 GitHub Pages 把网站免费部署到公网最后借助 GitHub Actions 把“每次手动上传”变成“推送代码后自动发布”。1. 背景与核心概念在动手之前先花几分钟把几个关键概念讲清楚。只有理解了它们各自负责什么后续配置过程中遇到报错时才知道该往哪个方向排查。1.1 为什么你的网站别人进不去很多初学者用 Codex 开发完网站后发现别人访问不了根本原因通常只有一个网站只运行在你自己电脑上。Codex 帮你在本地启动了一个服务地址往往是http://localhost:3000或http://127.0.0.1:8080。localhost的意思是“本机回环地址”它只代表你当前这台电脑。朋友、同事、网上的陌生人访问这个地址时指向的是他们自己的电脑自然什么都看不到。想要让别人也访问到必须做一次“部署”在服务器上准备一个可访问的静态目录把你的 HTML、CSS、JS 文件上传上去通过一个公网地址对外提供服务。GitHub Pages 就是帮你完成这整套流程的免费方案而且不需要自己买服务器、装 Nginx、配域名。1.2 Codex 是什么Codex 是 OpenAI 推出的 AI 编程代理工具官方名称叫 Codex CLI后来也提供了桌面版和 IDE 插件。它的核心是“代理式”编程你给它一个任务描述它不只是补全一段代码而是会自己分析问题、列出计划、修改多个文件、执行命令、查看运行结果然后继续迭代直到任务完成。相比传统的“在聊天窗口里复制代码再粘贴”Codex 更接近一个“能读懂你项目目录的 AI 开发助手”。你可以直接对它说把当前项目改成响应式布局顺便修复导航栏在移动端不显示的问题它会读取项目文件、修改对应代码、运行验证并告诉你改了什么。1.3 GitHub Pages 是什么GitHub Pages 是 GitHub 提供的静态网站托管服务它可以把仓库里的静态文件直接变成一个可访问的网站。它的典型特点包括免费不需要单独付费自动构建支持 Jekyll也能配合 GitHub Actions 构建前端项目稳定静态资源走 CDN访问速度在多数地区都不错上线快开启后几分钟内就能通过https://用户名.github.io访问。它适合个人主页、项目介绍站、产品落地页、技术文档站、简历页等纯前端网站。如果你的网站只有 HTML、CSS、JS没有后端服务那 GitHub Pages 是非常理想的托管方案。1.4 适用场景与边界用 Codex GitHub Pages 组合最舒服的场景是场景是否适合个人简介主页非常适合项目展示页 / 落地页非常适合前端框架静态站点Vite、React、Vue 打包后适合配合 Actions 自动化技术文档 / 博客适合可配合 Jekyll 或静态博客生成器需要后端接口的业务系统不适合Pages 只托管静态文件需要注册登录、数据库写入的网站不适合需要额外的后端服务需要按请求计费或被高频访问的接口服务不适合简单来说纯前端、内容型页面强烈推荐动态业务系统请老老实实买服务器。2. 环境准备与前置条件开始前需要先把环境准备齐全。下面这些工具和账号是必需的缺一个都会中途卡住。2.1 准备工作清单项目说明GitHub 账号用于创建仓库和开启 PagesGit用于本地提交代码并推送到远程仓库Node.jsCodex CLI 基于 Node.js 安装运行Codex CLI 或桌面版AI 编程工具本文以 CLI 为例浏览器用于本地预览和访问线上域名版本说明具体版本更新较快本文不写死某个版本号。Node.js 建议使用官方 LTS 版本Codex 建议通过官方文档安装最新版本。如果你已经装有旧版本优先升级到最新版避免因为版本过旧导致指令无法识别。2.2 安装 Git 与 Node.jsGit 的安装不做特殊介绍Windows 用户直接下载安装包macOS 用户如果装了 Homebrew可以执行brew install git安装完成后确认版本git --versionNode.js 可以直接从官网下载 LTS 安装包安装完成后确认node -v npm -v出现版本号即说明安装成功。3. Codex 安装、登录与基础使用Codex 是这篇文章的“生产力核心”。这部分我会完整演示安装、登录以及如何用 Codex 生成一个小型个人网站。3.1 安装 Codex CLICodex CLI 的官方包名是openai/codex通过 npm 全局安装即可npm install -g openai/codex安装完成后执行codex --version能打印出版本号说明安装成功。如果你更习惯图形界面也可以直接从 OpenAI 官网下载 Codex 桌面版或者在 VS Code 插件市场搜索 Codex。后面步骤里我用 CLI 操作桌面版的操作逻辑是一样的只是交互方式不同。3.2 登录 Codex安装好之后第一次使用需要登录认证。在终端运行codex login命令执行后浏览器会弹出登录页面完成账号授权后回到终端会看到登录成功的提示。如果你的网络环境无法直接访问官方接口或者你使用的是第三方兼容接口需要在 Codex 的配置文件中调整base_url、模型名称等参数。注意不同兼容网关的参数格式不完全一样建议以你使用的服务商文档为准。常见做法是在配置里指定model 你的模型名 model_provider 你的服务商标识这里的配置思路是通用的Codex 本身只是一个客户端真正响应任务的是模型接口。只要接口协议兼容Codex 就能正常工作。不过这一步不是必须的如果你能正常访问官方接口跳过这里即可。3.3 使用 Codex 生成个人网站先在本地创建一个项目目录mkdir my-site cd my-site接下来启动 Codex让它帮我们在当前目录生成一个完整的静态网站。在终端执行codex进入交互界面后输入你的需求。我用的提示词参考如下请在当前目录下创建一个个人网站项目要求 1. 使用纯 HTML、CSS、JavaScript不使用框架 2. 包含首页 index.html、样式文件 style.css、脚本文件 script.js 3. 页面包含三个区块自我介绍、项目展示、联系方式 4. 风格简洁现代适合个人开发者展示 5. 样式使用响应式布局手机端也能正常查看 6. 所有资源文件使用相对路径方便部署到 GitHub Pages。Codex 会先列出实施计划然后逐个创建文件。任务执行过程中它会读取目录内容、生成文件、必要时运行命令验证。完成后你会看到my-site目录下出现了几个文件my-site/ ├── index.html ├── style.css ├── script.js └── README.md这一步的核心价值在于你不用手动从零写页面代码Codex 根据自然语言需求把项目骨架搭好了。下面是一个简单版的index.html示例方便你理解生成结果大概长什么样。实际生成的内容可能更丰富!DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / title我的个人网站/title link relstylesheet hrefstyle.css / /head body header h1你好我是示例博主/h1 p一个喜欢折腾代码的开发者/p /header section idabout h2关于我/h2 p这里可以放自我介绍比如技术方向、工作经历、兴趣爱好。/p /section section idprojects h2项目展示/h2 ul li项目一Codex 实战教程/li li项目二GitHub Pages 自动部署/li /ul /section section idcontact h2联系方式/h2 p邮箱exampleexample.com/p /section script srcscript.js/script /body /html这里需要特别提醒提示词里一定要加上“使用相对路径”这一条。如果生成的代码里写的是/style.css这种绝对根路径在 GitHub Pages 项目页地址形式为https://用户名.github.io/仓库名/下会出现样式加载不到的问题。这是一个很典型的部署坑。4. 本地预览与验证网站代码生成后不要急着推送到 GitHub先在本地跑一遍确认页面和功能都正常。4.1 本地启动静态服务在项目目录下执行python3 -m http.server 8000如果你没装 Python也可以用 npx 启动一个静态服务npx serve .然后浏览器访问http://localhost:8000如果页面正常显示说明静态资源路径没有问题。4.2 检查文件结构用ls或资源管理器确认目录结构是否是预期结果。如果项目里生成了类似node_modules的目录推送前要排除掉这些文件不需要进仓库。如果你是第一次接触 Git 和 GitHub建议在执行推送命令前先配置用户名和邮箱git config --global user.name 你的用户名 git config --global user.email 你的邮箱4.3 本地预览时的常见错误错误现象原因解决办法页面白屏JS 报错或资源路径错误打开浏览器开发者工具的 Console 查看报错样式不生效CSS 路径写错检查link标签的href是相对路径还是绝对路径点击按钮无反应脚本加载失败检查script标签的src确认文件存在于指定路径这一步是整个流程里成本最低的检测环节。本地验证通过再进入部署阶段能帮你避免在线上反复调试。5. 推送到 GitHub 并开启 GitHub Pages代码在本地跑通后下一步就是把项目推送到 GitHub然后开启 Pages 服务。这也是解决“别人访问不了”的关键一步。5.1 创建 GitHub 仓库登录 GitHub点击右上角“”号选择“New repository”。仓库命名有一个小技巧如果你想得到一个https://用户名.github.io的主站点地址仓库名必须叫用户名.github.io。你注册 GitHub 时给自己起的名字如果是zhangsan那么仓库名就是zhangsan.github.io这样开启 Pages 后访问地址就是https://zhangsan.github.io如果仓库名是其他名字比如my-site那么访问地址是https://zhangsan.github.io/my-site/创建仓库时如果你想省事可以不勾选“Add a README file”因为本地项目已经有文件了。请注意免费版 GitHub 上公开仓库才能使用 GitHub Pages。可以先把仓库设为 Public。5.2 推送代码到远程仓库在本地项目目录执行以下命令git init git add . git commit -m Initial commit: personal website git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main推送提示失败时先检查远程地址是否写错GitHub 账号是否已完成 SSH 或 HTTPS 认证仓库是否已经存在同名文件导致冲突。5.3 开启 GitHub Pages进入仓库页面点击Settings在左侧菜单找到Pages。在Build and deployment区域Source 选择Deploy from a branchBranch 选择main目录选择/ (root)点击 Save。等待一两分钟后刷新页面会出现一行提示Your site is live at https://你的用户名.github.io/你的仓库名/打开这个地址你会看到和本地一模一样的页面。把链接发给任何人对方都能直接访问。到这里“开发完网站别人不能访问”的问题就解决了。但还有一个痛点没解决每次改完代码都要手动上传吗6. 让“手动上传”变成“自动发布”很多同学发布网站的流程是修改代码git push手动去 GitHub 重新构建等页面更新。如果只做一次还好每周迭代一次就非常痛苦。更严重的是有时候忘了重新构建线上内容还是旧的。解决办法就是GitHub Actions 自动部署。6.1 自动化部署原理GitHub Actions 是 GitHub 提供的持续集成/持续部署CI/CD服务。你可以把它理解成“在 GitHub 服务器上运行的自动化脚本”。我们只需要在仓库中放置一个工作流配置文件以后只要你把代码推送到指定分支GitHub 就会自动执行部署流程。所以完整流程变成本地修改代码 ↓ git add . git commit -m 更新内容 ↓ git push ↓ GitHub Actions 自动构建并部署 ↓ 线上页面自动更新6.2 编写 GitHub Actions 工作流在项目根目录创建.github/workflows/deploy.yml目录和文件name: Deploy to GitHub Pages on: push: branches: [ main ] permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup GitHub Pages uses: actions/configure-pagesv4 - 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 的权限Upload artifact步骤把当前目录下的所有文件上传为部署产物Deploy to GitHub Pages步骤完成实际的发布动作。如果你的项目是用 Vite、React、Vue 这类前端框架构建的需要先安装依赖并打包再上传打包目录工作流会多两步- name: Install dependencies run: npm install - name: Build run: npm run build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: dist对于本文的纯静态网站来说不需要构建步骤直接把当前目录上传即可。配置好后把文件推送到 GitHubgit add . git commit -m Add GitHub Actions deploy workflow git push然后打开仓库的Actions标签页可以看到工作流正在运行。运行结束后Pages 设置里如果 Sources 还没改可以把它改成GitHub Actions模式这样后续发布就完全交给工作流处理了。以后再修改网站内容只需要git add . git commit -m 更新项目介绍 git push等一两分钟线上页面自动更新。这就是“自动发布”的完整落地。7. 常见问题与排查思路整理几个最常见的坑按现象、原因、解决方法列出来遇到问题可以对照排查。问题现象常见原因解决思路访问域名显示 404Pages 没有开启或分支/目录选错检查 Settings → Pages 的 Source 和 Branch 配置页面显示但没有样式资源路径使用了绝对路径把所有href、src改成相对路径推送代码后页面不更新没有配置 Actions或 Actions 运行失败查看 Actions 日志确认部署流程是否执行成功git push失败远程仓库有本地没有的提交先git pull --rebase再重新推送Codex 命令提示找不到Node.js 未安装或全局路径未配置重新安装 Node.js确认 npm 全局目录在 PATH 中Codex 登录后报认证失败登录凭证过期或网络异常重新执行codex login检查接口地址配置使用第三方模型时接口返回 400提示reasoning_content相关错误某些模型在思考模式下要求把reasoning_content原样传回查阅你的兼容网关文档调整参数透传方式或关闭思考模式其中最后一个问题如果你使用的是社区兼容网关或第三方模型接口确实比较常见。不同的网关对reasoning_content的处理策略不一样解决思路主要是看网关文档以及在 Codex 配置里调整对应的模型参数。这部分没有统一答案关键是先看错误信息里提示的是哪个字段。8. 最佳实践与工程建议8.2 仓库与分支管理建议仓库名直接采用用户名.github.io这样线上地址最短、最好记也方便后续绑定自定义域名。主分支使用main。Actions 工作流默认监听main分支名不一致会导致自动化不触发。每次提交信息写清楚“改了什么”比如更新项目列表、修复移动端样式不要写update、test这种无意义提交。8.2 资源与构建产物管理所有资源路径使用相对路径不要写/style.css这种根路径使用 Git 忽略文件.gitignore把不需要入库的内容排除掉例如node_modules/ .DS_Store dist/ .env如果使用前端框架不要让dist、build这类打包产物直接入库应该由 Actions 在服务器上构建。8.3 安全边界不要把 API Key、Token、数据库连接串提交到仓库。即使是私有仓库也不建议保存真实密钥因为密钥一旦进入 Git 历史很难彻底清除GitHub Pages 是公开站点任何上传到静态目录的文件都可能被访问。不要往网站目录里放后台配置、备份文件、内网地址等信息如果后续要使用自定义域名在仓库 Settings → Pages 里配置 Custom domain并在域名服务商处添加 CNAME 记录指向用户名.github.io。8.4 自动化流程建议第一次配置 Actions 时先故意修改一个小文件并推送观察整个流程是否能跑通Pages 设置里 Sources 选择GitHub Actions后后续发布完全由 Actions 管理不要再手动选择分支部署两者不要混用否则容易产生“不知道哪个生效”的困惑本地提交前先git status确认没有多余文件尤其是.env、node_modules。8.5 使用 Codex 的小技巧需求描述越具体生成结果越接近预期。让 Codex “做一个网站”太宽泛建议说明技术栈、页面区块、风格方向同一项目反复使用 Codex 时把项目背景写在一个README.md里Codex 读取后能更好地理解项目上下文Codex 生成代码后仍然需要自己读一遍核心代码特别是涉及上传、删除、执行命令这类操作时要确认它不会执行危险命令。9. 结语与下一步建议到这里你已经掌握了三条核心技能用 Codex 快速生成静态网站用 GitHub Pages 免费把网站部署到公网用 GitHub Actions 实现推送代码后自动发布。如果你按照上面的步骤操作现在应该拥有一个可以分享给任何人的线上地址并且每次改完内容只需要git push就能完成发布。建议你接下来做三件事把网站的自我介绍改成自己的真实信息顺便练习一次“修改 → 推送 → 自动更新”的完整流程如果网站是纯静态页面可以继续尝试接入一个前端框架比如 Vite Vue 或 React然后修改 Actions 工作流加入构建步骤用 Codex 给网站加一些更复杂的功能比如项目筛选、动画效果、暗黑模式把这个免费托管的个人网站当成长期迭代的试验场。如果这篇文章对你有帮助可以收藏备用如果在操作中遇到其他问题也欢迎把报错信息留在评论区一起讨论排错思路。
