tyc-webview-v2/scripts/seo-static-generator/README.md

# 天远查 SEO 静态页面生成器

为 Vue SPA 应用生成 SEO 友好的静态 HTML 页面，解决爬虫无法抓取客户端渲染内容的问题。

## 功能特性

- ✅ 自动根据路由和 SEO 配置生成静态 HTML 页面
- ✅ 完整的 TDK（Title、Description、Keywords）优化
- ✅ 支持 Open Graph 和 Twitter Cards
- ✅ 包含 Schema.org 结构化数据
- ✅ 自动生成 sitemap.xml
- ✅ 自动生成 robots.txt
- ✅ Nginx 和 Apache 配置生成
- ✅ 爬虫检测中间件
- ✅ 复用现有的 useSEO.js 配置

## 目录结构

```
scripts/seo-static-generator/
├── package.json                    # 项目配置
├── README.md                        # 使用说明
├── pageTemplates.js                # 页面模板生成器
├── generateStaticPages.js          # 静态页面生成主脚本
├── crawlerMiddleware.js            # 爬虫检测中间件
├── generateNginxConfig.js          # 配置文件生成脚本
└── static-pages/                    # 生成的静态页面（自动创建）
    ├── index.html
    ├── inquire-category-lawsuit.html
    ├── inquire-marriage.html
    ├── ...
    ├── sitemap.xml
    └── robots.txt
```

## 快速开始

### 1. 安装依赖

```bash
cd scripts/seo-static-generator
```

注意：本工具使用 Node.js 原生模块，无需安装额外依赖。

### 2. 生成静态页面

```bash
# 生成所有静态页面
node generateStaticPages.js

# 或使用 npm script
npm run generate
```

生成成功后，静态页面将保存在 `static-pages/` 目录中。

### 3. 生成服务器配置

```bash
# 生成 Nginx 配置
npm run nginx

# 或生成 Apache .htaccess 配置
npm run htaccess
```

## 配置说明

### SEO 配置

SEO 配置在 `generateStaticPages.js` 中定义，可以直接复用 `useSEO.js` 中的配置：

```javascript
const seoConfigs = {
    '/': {
        title: '天远查官网_企业与婚姻关联风险核验_综合履约背景核验',
        description: '天远查官网(TianYuanCha)聚合官方公示数据...',
        keywords: '天远查,婚姻状态风险, 配偶背景核验...'
    },
    '/inquire/category/lawsuit': {
        title: '司法涉诉核验_个人及企业法律诉讼记录...',
        description: '天远查司法风险检测中心...',
        keywords: '司法案件核验,法律诉讼记录...'
    },
    // ... 更多路由配置
};
```

### Nginx 配置

在 `generateNginxConfig.js` 中修改配置：

```javascript
const config = {
    serverName: 'www.tianyuancha.cn',        // 你的域名
    spaRoot: '/var/www/tyc-webview-v2/dist', // SPA 静态文件目录
    staticRoot: '/var/www/tyc-webview-v2/static-pages', // SEO 静态页面目录
    sslEnabled: false,                       // 是否启用 HTTPS
    sslCertPath: '/etc/nginx/ssl/cert.pem',  // SSL 证书路径
    sslKeyPath: '/etc/nginx/ssl/key.pem'      // SSL 密钥路径
};
```

## 部署步骤

### 方式一：Nginx 部署（推荐）

1. **生成静态页面**

```bash
npm run generate
```

2. **生成 Nginx 配置**

```bash
npm run nginx
```

3. **部署配置文件**

```bash
# 复制生成的 nginx.conf 到 Nginx 配置目录
sudo cp scripts/seo-static-generator/nginx.conf /etc/nginx/sites-available/tyc-webview

# 创建软链接
sudo ln -s /etc/nginx/sites-available/tyc-webview /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo nginx -s reload
```

4. **部署静态文件**

```bash
# 将生成的静态页面复制到服务器
scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/
```

### 方式二：Apache 部署

1. **生成静态页面**

```bash
npm run generate
```

2. **生成 .htaccess 配置**

```bash
npm run htaccess
```

3. **部署配置文件**

```bash
# 复制 .htaccess 到网站根目录
cp scripts/seo-static-generator/.htaccess /var/www/tyc-webview-v2/
```

4. **部署静态文件**

```bash
# 将生成的静态页面复制到服务器
scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/
```

## 工作原理

### 爬虫检测流程

```
用户请求
    ↓
Nginx 检测 User-Agent
    ↓
    ├─ 是爬虫 → 返回静态页面（static-pages/）
    └─ 否      → 返回 SPA 应用（dist/）
```

### 爬虫 User-Agent 列表

工具内置了以下爬虫的识别：

- **Google**: googlebot, googlebot-image, googlebot-news
- **百度**: baiduspider, baiduspider-mobile
- **必应**: bingbot, msnbot
- **360**: 360spider
- **搜狗**: sogou spider, sogou-orion
- **头条**: bytespider
- **神马**: yisouspider
- **其他**: yandex, duckduckbot, slurp 等

## 自定义页面内容

### 修改页面模板

编辑 `pageTemplates.js` 中的模板函数：

```javascript
export function generateStaticHTML(seoConfig, options = {}) {
    // 自定义 HTML 模板
}
```

### 添加新的路由页面

1. 在 `generateStaticPages.js` 中添加路由配置：

```javascript
const seoConfigs = {
    '/new-route': {
        title: '新页面标题',
        description: '新页面描述',
        keywords: '关键词1,关键词2'
    }
};
```

2. 在 `pageTemplates.js` 中添加内容生成函数：

```javascript
function generateNewRouteContent(seoConfig) {
    return `
        <h2>新页面内容</h2>
        <p>这里写页面的具体内容...</p>
    `;
}

// 添加到路由映射
export function generateContentByRoute(path, seoConfig) {
    const routeContentMap = {
        '/new-route': generateNewRouteContent(seoConfig),
        // ... 其他路由
    };
    return routeContentMap[path] || generateDefaultContent(seoConfig);
}
```

## 集成到构建流程

在项目的 `package.json` 中添加构建脚本：

```json
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "build:seo": "node scripts/seo-static-generator/generateStaticPages.js",
    "build:all": "npm run build && npm run build:seo"
  }
}
```

现在运行 `npm run build:all` 就可以同时构建 SPA 和生成静态页面。

## 测试

### 测试爬虫检测

使用 curl 模拟爬虫访问：

```bash
# 模拟百度爬虫
curl -A "Baiduspider" http://www.tianyuancha.cn/

# 模拟 Google 爬虫
curl -A "Googlebot" http://www.tianyuancha.cn/

# 正常浏览器访问
curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" http://www.tianyuancha.cn/
```

### 验证 SEO

使用在线工具验证生成的页面：

- Google Rich Results Test: https://search.google.com/test/rich-results
- 百度移动适配测试: http://ziyuan.baidu.com/
- Schema Markup Validator: https://validator.schema.org/

## 常见问题

### Q: 如何添加新的爬虫识别？

A: 在 `crawlerMiddleware.js` 的 `SEARCH_ENGINE_BOTS` 数组中添加：

```javascript
const SEARCH_ENGINE_BOTS = [
    // ... 现有爬虫
    'new-bot-name',
];
```

### Q: 静态页面如何保持最新？

A: 每次更新 SEO 配置后，重新运行：

```bash
npm run generate
```

建议将此步骤集成到 CI/CD 流程中。

### Q: 如何处理动态内容？

A: 对于需要动态内容的页面，可以考虑：

1. 使用定时任务定期重新生成静态页面
2. 使用方案三（动态渲染服务）
3. 在静态页面中添加 JavaScript，让正常用户访问时加载动态内容

### Q: Nginx 配置不生效怎么办？

A: 检查以下几点：

1. 确保 Nginx 已重启：`sudo nginx -s reload`
2. 检查配置文件语法：`sudo nginx -t`
3. 查看 Nginx 错误日志：`sudo tail -f /var/log/nginx/error.log`
4. 确保静态文件路径正确

## 技术支持

如有问题，请联系技术团队或提交 Issue。

## 许可证

MIT