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

# SEO 静态页面集成指南

本文档说明如何将 SEO 静态页面生成器集成到天远查项目中。

## 快速开始

### 1. 生成静态页面

在项目根目录运行：

```bash
# Windows PowerShell
node scripts\seo-static-generator\generateStaticPages.js

# 或者使用 cmd
node scripts\seo-static-generator\generateStaticPages.js
```

这将生成所有 SEO 优化的静态页面到 `scripts/seo-static-generator/static-pages/` 目录。

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

```bash
# 生成 Nginx 配置
node scripts\seo-static-generator\generateNginxConfig.js
```

这将生成：
- `scripts/seo-static-generator/nginx.conf` - Nginx 配置文件
- `scripts/seo-static-generator/.htaccess` - Apache 配置文件

### 3. 集成到构建流程

更新 `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",
    "config:nginx": "node scripts/seo-static-generator/generateNginxConfig.js"
  }
}
```

现在可以使用：

```bash
# 构建项目并生成 SEO 页面
npm run build:all

# 只生成 SEO 页面
npm run build:seo

# 生成 Nginx 配置
npm run config:nginx
```

## 部署步骤

### 开发环境测试

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

```bash
npm run build:seo
```

2. **在浏览器中打开测试**

```bash
# 在浏览器中打开示例页面
start scripts\seo-static-generator\index.html
```

### 生产环境部署

#### 使用 Nginx（推荐）

1. **构建项目**

```bash
npm run build:all
```

2. **生成 Nginx 配置**

```bash
npm run config:nginx
```

3. **上传文件到服务器**

```bash
# 上传 SPA 构建文件
scp -r dist/* user@server:/var/www/tyc-webview-v2/dist/

# 上传 SEO 静态页面
scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/

# 上传 Nginx 配置
scp scripts/seo-static-generator/nginx.conf user@server:/etc/nginx/sites-available/tyc-webview
```

4. **配置 Nginx**

```bash
# 在服务器上执行

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

# 测试配置
sudo nginx -t

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

#### 使用 Apache

1. **构建项目**

```bash
npm run build:all
```

2. **生成 Apache 配置**

生成的 `.htaccess` 文件在 `scripts/seo-static-generator/.htaccess`

3. **上传文件到服务器**

```bash
# 上传 SPA 构建文件
scp -r dist/* user@server:/var/www/tyc-webview-v2/

# 上传 SEO 静态页面
scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/

# 上传 .htaccess
scp scripts/seo-static-generator/.htaccess user@server:/var/www/tyc-webview-v2/
```

4. **确保 Apache 启用了 mod_rewrite**

```bash
# 在服务器上执行
sudo a2enmod rewrite
sudo systemctl restart apache2
```

## 配置说明

### 修改服务器配置

#### Nginx 配置

编辑 `scripts/seo-static-generator/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 密钥路径
};
```

#### Apache 配置

Apache 使用 `.htaccess` 文件，无需额外配置，确保：

- `static-pages/` 目录与网站根目录同级
- Apache 启用了 `mod_rewrite` 模块

### 修改 SEO 配置

SEO 配置在 `scripts/seo-static-generator/generateStaticPages.js` 中：

```javascript
const seoConfigs = {
    '/': {
        title: '天远查官网_企业与婚姻关联风险核验_综合履约背景核验',
        description: '天远查官网(TianYuanCha)聚合官方公示数据...',
        keywords: '天远查,婚姻状态风险, 配偶背景核验...'
    },
    // ... 添加更多路由
};
```

## 测试验证

### 1. 测试爬虫检测

使用 curl 模拟爬虫访问：

```bash
# 模拟百度爬虫（应该返回静态页面）
curl -A "Baiduspider" http://www.tianyuancha.cn/

# 模拟 Google 爬虫（应该返回静态页面）
curl -A "Googlebot" http://www.tianyuancha.cn/

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

### 2. 验证 SEO

使用在线工具验证：

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

### 3. 检查生成的文件

```bash
# 检查静态页面目录
ls -la scripts/seo-static-generator/static-pages/

# 检查 sitemap.xml
cat scripts/seo-static-generator/static-pages/sitemap.xml

# 检查 robots.txt
cat scripts/seo-static-generator/static-pages/robots.txt
```

## 维护和更新

### 更新 SEO 配置

1. 修改 `scripts/seo-static-generator/generateStaticPages.js` 中的 `seoConfigs`

2. 重新生成静态页面：

```bash
npm run build:seo
```

3. 部署到服务器：

```bash
# 上传更新的静态页面
scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/
```

### 添加新路由

1. 在 `scripts/seo-static-generator/generateStaticPages.js` 中添加路由：

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

2. 在 `scripts/seo-static-generator/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);
}
```

3. 重新生成静态页面：

```bash
npm run build:seo
```

## 集成到 CI/CD

在 CI/CD 流程中添加静态页面生成：

```yaml
# .github/workflows/deploy.yml 示例
name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm install

    - name: Build project
      run: npm run build:all

    - name: Deploy to server
      run: |
        scp -r dist/* user@server:/var/www/tyc-webview-v2/dist/
        scp -r scripts/seo-static-generator/static-pages/* user@server:/var/www/tyc-webview-v2/static-pages/
```

## 常见问题

### Q: 静态页面没有生成？

A: 检查以下几点：

1. 确保 Node.js 版本 >= 14
2. 检查是否有文件写入权限
3. 查看控制台错误信息

### Q: Nginx 配置不生效？

A: 检查以下几点：

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

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

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

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

### Q: 爬虫仍然看到的是 SPA？

A: 检查以下几点：

1. 确认 User-Agent 匹配规则正确
2. 检查 Nginx/Apache 配置是否正确加载
3. 使用 curl 测试爬虫访问

## 技术支持

如有问题，请参考详细文档：`scripts/seo-static-generator/README.md`