1. 为什么静态站点要同时上 GitHub Pages 和 Nginx个人静态站点最常见的两种发布方式一种是托管到 GitHub Pages另一种是丢到自己的服务器上用 Nginx 提供服务。前者免费、自带 HTTPS、推代码就上线适合做展示和备份后者可控、能挂自定义域名、能加缓存和鉴权适合做正式入口。很多人的真实需求是同一份构建产物两边都要能跑而且路由、资源路径、子目录访问都不能出问题。我这次要处理的场景是一个用 Umi 4 React 18 搭的前端工具集构建后输出到dist/。它既要发布到https://用户名.github.io/也要部署到自建服务器的/var/www/site目录下。听起来只是复制文件但实际踩坑集中在三处SPA 子路由在 GitHub Pages 上直接访问返回 404、Nginx 下静态资源路径错乱、以及构建和部署流程里缺少统一的配置骨架导致每次改完都要手动核对一遍。这篇不聊虚的直接给一套可复制的配置骨架一份提示词模板帮你把项目上下文喂给 AI 助手一份 Nginxserver配置一段 GitHub Actions 工作流再加上本地curl和线上路径的双重验证动作。目标很明确——你照着改完双端一次跑通。中间涉及统一 Key 和 API 通道的部分我会用 TaoToken 的settings.json示例串起来方便你在同一套工程里管理模型调用配置。2. TaoToken 前置统一 Key 与 API 通道的 settings.json在双部署项目里前端构建本身不一定需要模型调用但如果你用 AI 助手参与生成配置、排查报错、写工作流就会涉及一个统一入口的问题。TaoToken 在这里扮演的角色是提供统一的 API 通道和 Key 管理让你不用在多个工具之间来回切换配置。先拿到 Key。打开控制台创建 API Key地址是https://taotoken.net/console。创建后复制保存后面写进settings.json。{ provider: taotoken, api_base: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet, timeout: 60, retry: 2 }这份settings.json放在项目根目录或者你的工具配置目录下都行关键是api_base指向https://taotoken.net/api不要带多余路径。model字段按你实际用的模型填timeout和retry是给网络波动留的余量。如果你更习惯在对话界面里验证模型连通性可以直接用模型对话入口https://taotoken.net/models。想先确认 Key 是否生效最省事的办法是发一条最小请求看返回结构对不对。curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}] }返回里能看到choices字段就说明通道通了。这一步别跳过很多人后面工作流报错其实是 Key 或api_base写错跟部署本身没关系。注意api_base只写到/api具体接口路径由客户端拼接不要手动加/v1之外的冗余段。3. 可复制配置Nginx server 骨架与 GitHub Actions 工作流3.1 Nginx server 配置骨架Nginx 这块的核心是两件事静态资源能正确命中SPA 子路由回退到index.html。下面这份配置可以直接改域名和目录用。server { listen 80; server_name example.com www.example.com; root /var/www/site; index index.html; # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|svg|woff2?)$ { expires 7d; add_header Cache-Control public, max-age604800; try_files $uri 404; } # SPA 主入口回退 location / { try_files $uri $uri/ /index.html; } # 子路由显式回退避免深层路径 404 location ~ ^/(tools|blog|pricing)/ { try_files $uri $uri/ /index.html; } # 关闭目录列表 autoindex off; }几个参数说明一下。try_files $uri $uri/ /index.html是 SPA 的标准回退写法先找真实文件找不到就交给前端路由。location ~ ^/(tools|blog|pricing)/这段是针对已知子路由的显式回退实测下来比只靠主location更稳尤其是带尾斜杠的访问。静态资源那段单独拎出来加缓存避免每次刷新都重新拉 JS。改完配置先测语法再重载sudo nginx -t sudo systemctl reload nginxnginx -t返回syntax is ok和test is successful才算过。如果报unexpected }多半是括号没配对逐段核对。3.2 GitHub Actions 工作流片段GitHub Pages 这边用 Actions 自动构建发布。下面这段放在.github/workflows/deploy.yml。name: Deploy to GitHub Pages on: push: branches: [main] permissions: contents: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 18 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm run build - uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist publish_branch: gh-pagespermissions: contents: write是必须的否则推送gh-pages分支会被拒。publish_dir指向构建输出目录publish_branch指定发布分支。cache: pnpm能省不少安装时间。3.3 构建配置里的路径处理双部署最容易翻车的地方是资源路径。构建配置里把publicPath设成相对路径两边都能兼容。// .umirc.ts 关键片段 export default { base: /, publicPath: ./, hash: true, exportStatic: {}, runtimePublicPath: {}, };exportStatic: {}会为每个路由生成独立 HTML这是解决 GitHub Pages 子路由 404 的关键。publicPath: ./用相对路径Nginx 子目录部署时资源不会指错。runtimePublicPath配合相对路径做动态资源定位。4. 验证请求本地 curl 与线上路径双重检查配置写完不算完得验证。分两步走先本地再线上。本地构建后起一个静态服务模拟 Nginx 行为pnpm run build npx serve dist -l 3000然后 curl 几个关键路径看返回码和内容curl -I http://localhost:3000/ curl -I http://localhost:3000/tools/code-formatter curl -I http://localhost:3000/blog-I只看响应头。理想结果是全部返回200Content-Type是text/html。如果子路由返回404说明exportStatic没生效或者构建产物里缺对应 HTML。线上验证分两端。GitHub Pages 这边curl -I https://用户名.github.io/ curl -I https://用户名.github.io/tools/code-formatterNginx 这边curl -I http://example.com/ curl -I http://example.com/tools/code-formatter curl -I http://example.com/assets/index-abc123.js重点看第三个静态资源要返回200且Cache-Control带max-age。如果返回404多半是publicPath写成了绝对路径或者 Nginx 的root指错了目录。再补一个内容层面的检查确认返回的确实是你的页面而不是默认页curl -s http://example.com/ | grep -o title[^]*/title标题对得上说明请求打到了正确的index.html。5. 本篇常见错排查5.1 GitHub Pages 子路由直接访问 404现象是首页正常但刷新/tools/xxx就 404。原因是 GitHub Pages 是纯静态托管不认识前端路由。解决办法就是构建时开exportStatic为每个路由生成独立 HTML 文件。构建完检查dist/目录应该能看到tools/code-formatter/index.html这样的结构而不是只有一个根index.html。5.2 Nginx 下 JS/CSS 资源 404现象是页面能打开但样式全丢控制台一堆资源 404。根因是publicPath用了绝对路径/子目录部署时请求打到了错误位置。改成./相对路径配合runtimePublicPath。改完重新构建再 curl 一个具体资源文件确认。5.3 组件未导入导致的运行时错误这类错误跟部署无关但会在构建后暴露。典型报错是ReferenceError: Statistic is not defined原因是用了 Ant Design 的组件却没在 import 里加。排查方法是看报错文件名定位到具体组件检查 import 语句。// 修复前 import { Card, Upload, Button } from antd; // 修复后 import { Card, Upload, Button, Statistic } from antd;5.4 Actions 推送 gh-pages 被拒报错通常是remote: Permission to ... denied。检查工作流里有没有permissions: contents: write以及仓库设置里 Actions 的权限是否放开。另一个常见原因是GITHUB_TOKEN没传对确认with块里写了github_token: ${{ secrets.GITHUB_TOKEN }}。5.5 Nginx 重载后配置没生效改了配置但行为没变先确认nginx -t通过再确认reload执行成功。有时候是浏览器缓存了旧的 JS用curl加-H Cache-Control: no-cache绕过缓存验证。还有一种情况是配置改在了错误的server块里用nginx -T打印完整生效配置核对。6. 把配置骨架沉淀成可复用的提示词模板双部署这件事配置本身不复杂复杂的是每次新项目都要重新捋一遍路径、回退、缓存这些细节。我的做法是把上面这套骨架沉淀成一份提示词模板让 AI 助手在生成配置时直接带上项目上下文减少来回试错。模板大概长这样项目Umi 4 React 18 静态站点 构建输出dist/ 部署目标GitHub Pages 自建 Nginx 已知约束 - SPA 子路由需回退 index.html - 资源路径用相对路径 - Nginx root 为 /var/www/site 请生成 1. Nginx server 配置含静态资源缓存和子路由回退 2. GitHub Actions 工作流发布到 gh-pages 分支 3. 本地 curl 验证命令清单把这段连同你的settings.json一起交给助手生成的配置基本能直接用。涉及模型调用的部分统一走 TaoToken 的 API 通道Key 在控制台管理配置里只留api_base和占位 Key。这样换项目时只需要改域名和目录其余骨架不动。如果你后面要长期维护多个站点或者把部署流程接进 Agent 自动跑可以考虑用 Coding Plan 把构建、验证、发布串成一条流水线减少手动操作。接入文档里有完整的接口说明排障时对照着看能省不少时间。
1. 为什么静态站点要同时上 GitHub Pages 和 Nginx个人静态站点最常见的两种发布方式一种是托管到 GitHub Pages另一种是丢到自己的服务器上用 Nginx 提供服务。前者免费、自带 HTTPS、推代码就上线适合做展示和备份后者可控、能挂自定义域名、能加缓存和鉴权适合做正式入口。很多人的真实需求是同一份构建产物两边都要能跑而且路由、资源路径、子目录访问都不能出问题。我这次要处理的场景是一个用 Umi 4 React 18 搭的前端工具集构建后输出到dist/。它既要发布到https://用户名.github.io/也要部署到自建服务器的/var/www/site目录下。听起来只是复制文件但实际踩坑集中在三处SPA 子路由在 GitHub Pages 上直接访问返回 404、Nginx 下静态资源路径错乱、以及构建和部署流程里缺少统一的配置骨架导致每次改完都要手动核对一遍。这篇不聊虚的直接给一套可复制的配置骨架一份提示词模板帮你把项目上下文喂给 AI 助手一份 Nginxserver配置一段 GitHub Actions 工作流再加上本地curl和线上路径的双重验证动作。目标很明确——你照着改完双端一次跑通。中间涉及统一 Key 和 API 通道的部分我会用 TaoToken 的settings.json示例串起来方便你在同一套工程里管理模型调用配置。2. TaoToken 前置统一 Key 与 API 通道的 settings.json在双部署项目里前端构建本身不一定需要模型调用但如果你用 AI 助手参与生成配置、排查报错、写工作流就会涉及一个统一入口的问题。TaoToken 在这里扮演的角色是提供统一的 API 通道和 Key 管理让你不用在多个工具之间来回切换配置。先拿到 Key。打开控制台创建 API Key地址是https://taotoken.net/console。创建后复制保存后面写进settings.json。{ provider: taotoken, api_base: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet, timeout: 60, retry: 2 }这份settings.json放在项目根目录或者你的工具配置目录下都行关键是api_base指向https://taotoken.net/api不要带多余路径。model字段按你实际用的模型填timeout和retry是给网络波动留的余量。如果你更习惯在对话界面里验证模型连通性可以直接用模型对话入口https://taotoken.net/models。想先确认 Key 是否生效最省事的办法是发一条最小请求看返回结构对不对。curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}] }返回里能看到choices字段就说明通道通了。这一步别跳过很多人后面工作流报错其实是 Key 或api_base写错跟部署本身没关系。注意api_base只写到/api具体接口路径由客户端拼接不要手动加/v1之外的冗余段。3. 可复制配置Nginx server 骨架与 GitHub Actions 工作流3.1 Nginx server 配置骨架Nginx 这块的核心是两件事静态资源能正确命中SPA 子路由回退到index.html。下面这份配置可以直接改域名和目录用。server { listen 80; server_name example.com www.example.com; root /var/www/site; index index.html; # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|svg|woff2?)$ { expires 7d; add_header Cache-Control public, max-age604800; try_files $uri 404; } # SPA 主入口回退 location / { try_files $uri $uri/ /index.html; } # 子路由显式回退避免深层路径 404 location ~ ^/(tools|blog|pricing)/ { try_files $uri $uri/ /index.html; } # 关闭目录列表 autoindex off; }几个参数说明一下。try_files $uri $uri/ /index.html是 SPA 的标准回退写法先找真实文件找不到就交给前端路由。location ~ ^/(tools|blog|pricing)/这段是针对已知子路由的显式回退实测下来比只靠主location更稳尤其是带尾斜杠的访问。静态资源那段单独拎出来加缓存避免每次刷新都重新拉 JS。改完配置先测语法再重载sudo nginx -t sudo systemctl reload nginxnginx -t返回syntax is ok和test is successful才算过。如果报unexpected }多半是括号没配对逐段核对。3.2 GitHub Actions 工作流片段GitHub Pages 这边用 Actions 自动构建发布。下面这段放在.github/workflows/deploy.yml。name: Deploy to GitHub Pages on: push: branches: [main] permissions: contents: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 18 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm run build - uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist publish_branch: gh-pagespermissions: contents: write是必须的否则推送gh-pages分支会被拒。publish_dir指向构建输出目录publish_branch指定发布分支。cache: pnpm能省不少安装时间。3.3 构建配置里的路径处理双部署最容易翻车的地方是资源路径。构建配置里把publicPath设成相对路径两边都能兼容。// .umirc.ts 关键片段 export default { base: /, publicPath: ./, hash: true, exportStatic: {}, runtimePublicPath: {}, };exportStatic: {}会为每个路由生成独立 HTML这是解决 GitHub Pages 子路由 404 的关键。publicPath: ./用相对路径Nginx 子目录部署时资源不会指错。runtimePublicPath配合相对路径做动态资源定位。4. 验证请求本地 curl 与线上路径双重检查配置写完不算完得验证。分两步走先本地再线上。本地构建后起一个静态服务模拟 Nginx 行为pnpm run build npx serve dist -l 3000然后 curl 几个关键路径看返回码和内容curl -I http://localhost:3000/ curl -I http://localhost:3000/tools/code-formatter curl -I http://localhost:3000/blog-I只看响应头。理想结果是全部返回200Content-Type是text/html。如果子路由返回404说明exportStatic没生效或者构建产物里缺对应 HTML。线上验证分两端。GitHub Pages 这边curl -I https://用户名.github.io/ curl -I https://用户名.github.io/tools/code-formatterNginx 这边curl -I http://example.com/ curl -I http://example.com/tools/code-formatter curl -I http://example.com/assets/index-abc123.js重点看第三个静态资源要返回200且Cache-Control带max-age。如果返回404多半是publicPath写成了绝对路径或者 Nginx 的root指错了目录。再补一个内容层面的检查确认返回的确实是你的页面而不是默认页curl -s http://example.com/ | grep -o title[^]*/title标题对得上说明请求打到了正确的index.html。5. 本篇常见错排查5.1 GitHub Pages 子路由直接访问 404现象是首页正常但刷新/tools/xxx就 404。原因是 GitHub Pages 是纯静态托管不认识前端路由。解决办法就是构建时开exportStatic为每个路由生成独立 HTML 文件。构建完检查dist/目录应该能看到tools/code-formatter/index.html这样的结构而不是只有一个根index.html。5.2 Nginx 下 JS/CSS 资源 404现象是页面能打开但样式全丢控制台一堆资源 404。根因是publicPath用了绝对路径/子目录部署时请求打到了错误位置。改成./相对路径配合runtimePublicPath。改完重新构建再 curl 一个具体资源文件确认。5.3 组件未导入导致的运行时错误这类错误跟部署无关但会在构建后暴露。典型报错是ReferenceError: Statistic is not defined原因是用了 Ant Design 的组件却没在 import 里加。排查方法是看报错文件名定位到具体组件检查 import 语句。// 修复前 import { Card, Upload, Button } from antd; // 修复后 import { Card, Upload, Button, Statistic } from antd;5.4 Actions 推送 gh-pages 被拒报错通常是remote: Permission to ... denied。检查工作流里有没有permissions: contents: write以及仓库设置里 Actions 的权限是否放开。另一个常见原因是GITHUB_TOKEN没传对确认with块里写了github_token: ${{ secrets.GITHUB_TOKEN }}。5.5 Nginx 重载后配置没生效改了配置但行为没变先确认nginx -t通过再确认reload执行成功。有时候是浏览器缓存了旧的 JS用curl加-H Cache-Control: no-cache绕过缓存验证。还有一种情况是配置改在了错误的server块里用nginx -T打印完整生效配置核对。6. 把配置骨架沉淀成可复用的提示词模板双部署这件事配置本身不复杂复杂的是每次新项目都要重新捋一遍路径、回退、缓存这些细节。我的做法是把上面这套骨架沉淀成一份提示词模板让 AI 助手在生成配置时直接带上项目上下文减少来回试错。模板大概长这样项目Umi 4 React 18 静态站点 构建输出dist/ 部署目标GitHub Pages 自建 Nginx 已知约束 - SPA 子路由需回退 index.html - 资源路径用相对路径 - Nginx root 为 /var/www/site 请生成 1. Nginx server 配置含静态资源缓存和子路由回退 2. GitHub Actions 工作流发布到 gh-pages 分支 3. 本地 curl 验证命令清单把这段连同你的settings.json一起交给助手生成的配置基本能直接用。涉及模型调用的部分统一走 TaoToken 的 API 通道Key 在控制台管理配置里只留api_base和占位 Key。这样换项目时只需要改域名和目录其余骨架不动。如果你后面要长期维护多个站点或者把部署流程接进 Agent 自动跑可以考虑用 Coding Plan 把构建、验证、发布串成一条流水线减少手动操作。接入文档里有完整的接口说明排障时对照着看能省不少时间。
