通过提示词实现GitHub Pages 和 Nginx 双部署竟然这么简单？

⭐ 前言

大家好，我是yma16，本文分享一个基于 React 18 + TypeScript + Umi 4 + Ant Design 5 的前端开发工具集。项目集成了代码格式化、组件生成、性能检测、SVG 批量处理、文件对比等实用工具，并实现了 GitHub Pages + Nginx 双部署，本文将从项目架构、核心配置、部署方案到踩坑修复，完整剖析这个可复用的前端工程化实践。

yma16 前端开发工具集

项目源码：github.com/yongma16/yo...

⭐ 项目背景

在现代前端开发中，开发者经常需要在多个工具站之间来回切换：代码格式化、组件预览、性能检测、图片处理......这些零散需求催生了 yongma16.github.io 这个一站式前端工具集。项目采用 Umi 4 作为应用框架，配合 Ant Design 5 提供统一的 UI 体验，并针对 GitHub Pages 静态托管 与 Nginx 服务器部署 两种场景做了深度适配，解决了 SPA 子路由 404、资源路径错乱等经典难题。

⭐ 技术栈与项目结构

技术选型

依赖	版本	用途
React	18.2.0	UI 框架
TypeScript	5.3.0	类型系统
Umi	4.1.0	应用框架
Ant Design	5.14.0	UI 组件库
@monaco-editor/react	4.6.0	代码编辑器

项目结构

text 复制代码

react_home/
├── .umirc.ts              # Umi 配置文件
├── package.json           # 依赖管理
├── src/
│   ├── layouts/
│   │   └── index.tsx      # 全局布局组件 (导航栏 + 页脚)
│   ├── pages/
│   │   ├── index.tsx      # 首页 (工具展示 + 功能特性)
│   │   ├── blog.tsx       # 技术博客页面
│   │   ├── pricing.tsx    # 合作/定价页面
│   │   └── tools/
│   │       ├── code-formatter.tsx   # 代码格式化工具
│   │       ├── component-gen.tsx    # 组件生成器
│   │       ├── perf-check.tsx       # 性能检测工具
│   │       ├── svg-processor.tsx    # SVG 批量处理工具
│   │       └── file-diff.tsx        # 文件对比工具
│   └── config/
│       └── contact.ts     # 联系信息配置
├── dist/                  # 构建输出目录
└── .github/
    └── workflows/
        └── deploy.yml     # GitHub Actions 部署配置

⭐ 核心配置解析

Umi 配置 (.umirc.ts)

typescript 复制代码

// 关键配置项
{
  base: '/',
  publicPath: process.env.NODE_ENV === 'production' ? './' : '/',
  hash: true,
  ssr: false,
  exportStatic: {},           // 静态导出，为每个路由生成 HTML
  runtimePublicPath: {},      // 动态资源路径，兼容 Nginx 子目录部署
}

配置说明：

exportStatic：为每个路由生成独立 HTML 文件，解决直接访问子路由 404 问题
publicPath: './'：使用相对路径，兼容 Nginx 和 GitHub Pages 双部署
runtimePublicPath：配合相对路径，动态设置资源路径

Nginx 配置

nginx 复制代码

server {
    listen 80;
    server_name yma16.cloud www.yma16.cloud;
    root /var/www/yma16.cloud;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 子路由支持
    location ~ ^/(tools|blog|pricing)/ {
        try_files $uri $uri/ /index.html;
    }
}

⭐ 页面路由一览

路径	页面	状态
`/`	首页	✅ 正常
`/tools/code-formatter`	代码格式化	✅ 正常
`/tools/component-gen`	组件生成器	✅ 正常
`/tools/perf-check`	性能检测	✅ 正常
`/tools/svg-processor`	SVG 处理	✅ 已修复 (2026-08-30)
`/tools/file-diff`	文件对比	✅ 正常
`/blog`	技术博客	✅ 正常
`/pricing`	合作	✅ 正常

⭐ 核心功能实现

1. 全局布局组件

typescript 复制代码

// src/layouts/index.tsx
import { Layout, Menu } from 'antd'
import { Outlet, useNavigate } from 'umi'

export default function GlobalLayout() {
  const navigate = useNavigate()

  return (
    <Layout>
      <Layout.Header>
        <Menu
          mode="horizontal"
          onClick={({ key }) => navigate(key)}
          items={[
            { key: '/', label: '首页' },
            { key: '/tools/code-formatter', label: '代码格式化' },
            { key: '/blog', label: '技术博客' },
            { key: '/pricing', label: '合作' },
          ]}
        />
      </Layout.Header>
      <Layout.Content>
        <Outlet />
      </Layout.Content>
    </Layout>
  )
}

2. 工具页面示例（代码格式化）

typescript 复制代码

// src/pages/tools/code-formatter.tsx
import { Card, Select, Button } from 'antd'
import Editor from '@monaco-editor/react'

export default function CodeFormatter() {
  return (
    <Card title="代码格式化工具">
      <Select
        defaultValue="typescript"
        options={[
          { value: 'typescript', label: 'TypeScript' },
          { value: 'javascript', label: 'JavaScript' },
          { value: 'json', label: 'JSON' },
        ]}
      />
      <Editor
        height="400px"
        defaultLanguage="typescript"
        defaultValue="// 粘贴代码..."
      />
      <Button type="primary">格式化</Button>
    </Card>
  )
}

⭐ 部署方案：GitHub Pages + Nginx 双部署

1. GitHub Pages 部署（GitHub Actions）

yaml 复制代码

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: pnpm install
      - run: pnpm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

2. Nginx 部署

bash 复制代码

# 本地构建
pnpm run build

# 复制 dist 到服务器
cp -r dist/* /var/www/yma16.cloud/

# 重载 Nginx
sudo systemctl reload nginx

⭐ 踩坑记录与修复方案

1. SVG 处理器组件修复（2026-08-30）

问题： ReferenceError: Statistic is not defined

文件：src/pages/tools/svg-processor.tsx
原因：Statistic 组件未从 antd 导入
修复：在 import 语句中添加 Statistic

typescript 复制代码

// 修复前
import { Card, Upload, Button, ... } from 'antd';

// 修复后
import { Card, Upload, Button, ..., Statistic } from 'antd';

2. 路由工具无法打开（404 问题）

问题： GitHub Pages 直接访问 /tools/* 子路由返回 404

原因：GitHub Pages 是静态服务器，不支持 SPA history 路由回退
修复：启用 exportStatic 静态导出，为每个路由生成独立 HTML 文件

3. Nginx 部署资源路径问题

问题： Nginx 部署时子路由 JS 资源 404

原因：publicPath 使用绝对路径 /，子路由请求资源路径错误
修复：改为相对路径 ./，配合 runtimePublicPath 动态设置

⭐ 开发命令速查

bash 复制代码

# 安装依赖
pnpm install

# 开发模式
pnpm run dev          # http://localhost:8000

# 生产构建
pnpm run build        # 输出到 dist/ 目录

# 构建并部署到 Nginx
pnpm run build && sudo cp -r dist/* /var/www/yma16.cloud/ && sudo systemctl reload nginx

⭐ 总结

通过 yongma16.github.io 这个项目，我们可以收获：

工程化实践：Umi 4 + React 18 + TypeScript + Ant Design 5 的完整技术栈组合
双部署方案：一套代码同时适配 GitHub Pages 与 Nginx，解决 SPA 路由与资源路径难题
工具集设计：将零散的前端开发需求整合为统一入口，提升日常开发效率
踩坑经验：exportStatic、相对路径 publicPath、组件导入遗漏等实战问题的修复思路

总结提示词（Prompt）的重要性

在借助 OpenClaw、AI 编程助手等工具搭建项目时，总结提示词（Summary Prompt） 的质量直接决定了 AI 输出的可用性。所谓总结提示词，就是让 AI 对项目现状、技术栈、目录结构、已知问题与修复记录进行结构化归纳的指令。它的重要性体现在三个方面：

上下文对齐 ：一份高质量的总结提示词（如本文开头的 AGENTS.md）能让 AI 在数秒内理解项目的技术栈、目录约定与部署方式，避免「答非所问」或生成与现有架构冲突的代码。
问题定位加速 ：把「已知问题与修复记录」写进总结提示词，AI 在后续开发中会自动规避同类坑（如 Statistic 未导入、SPA 子路由 404），减少重复踩坑。
协作效率提升：无论是团队协作还是个人长期维护，一份结构化的总结提示词就是项目的「活文档」，让 AI 与人都能快速上手，把精力聚焦在业务逻辑而非环境摸索上。

如何写好总结提示词：

明确技术栈与版本号（如 React 18.2.0、Umi 4.1.0）
给出目录结构与关键文件职责
记录已知问题与修复方案，形成「避坑清单」
说明部署流程与常用命令，方便 AI 辅助运维

核心建议：

使用 exportStatic 解决静态托管的 SPA 子路由 404 问题
生产环境使用相对路径 publicPath: './' 提升部署兼容性
善用 GitHub Actions 实现自动化构建部署
工具类页面优先复用 Ant Design 组件，减少重复开发
维护一份高质量的总结提示词（如 AGENTS.md），让 AI 助手更懂你的项目

希望本文能帮助你更好地理解前端工程化与多环境部署实践。本文分享到这结束，如有错误或者不足之处欢迎指出！