tyc-webview-v2/server/README-SEO.md

# SPA SEO 优化解决方案

## 📋 方案概述

针对 SPA 应用 SEO 问题，采用**爬虫检测 + 静态 HTML 回退**方案：

1. **爬虫检测**：识别搜索引擎爬虫（百度、Google、必应、搜狗等）
2. **静态 HTML**：为爬虫提供预渲染的 HTML 模板，包含完整 TDK、OG、canonical、结构化数据
3. **正常用户**：继续使用 SPA，体验不受影响

**配置统一**：服务端 SEO 模板内容与前端 `src/composables/useSEO.js` 保持一致（标题、描述、关键词、域名），域名默认为 `https://www.tianyuancha.cn`（天远查）。可通过环境变量 `SEO_BASE_URL` 覆盖。

## 🏗️ 项目结构

```
server/
├── crawler-detector.js              # 爬虫检测模块
├── middleware.js                    # SEO 中间件（Express/Koa），路由与 useSEO.js 一致
├── generate-seo-templates.cjs       # SEO 模板生成器（与 useSEO.js 同步）
├── server-example-express.js        # Express 服务器示例
├── nginx-www.tianyuandb.com.conf      # 天远数据 Nginx 配置（tianyuandb.com）
├── nginx-www.xingfucha.cn.conf      # 幸福查 Nginx 配置示例
├── nginx-seo-location-替换片段.conf # Nginx SEO 片段
├── test-seo.js                      # SEO 端到端检测脚本
└── README-SEO.md                    # 本文档

public/
└── seo-templates/                   # SEO 静态模板目录（运行 generate 后生成）
    ├── index.html
    ├── inquire.html
    ├── inquire-category-lawsuit.html
    ├── inquire-category-vehicle.html
    ├── inquire-category-marriageStatus.html
    ├── inquire-marriage.html
    ├── agent.html
    ├── help.html
    ├── help-guide.html
    ├── example.html
    ├── service.html
    └── ...
```

## 🚀 快速开始

### 步骤1：生成 SEO 模板

```bash
cd server
node generate-seo-templates.cjs
# 或 npm run generate
```

这会在 `public/seo-templates/` 下生成所有页面的静态 HTML 模板，内容与 `src/composables/useSEO.js` 一致。

### 步骤2：集成到你的服务器

#### 选项A：使用Express服务器

```javascript
const express = require('express')
const SEOMiddleware = require('./server/middleware')

const app = express()

// 初始化SEO中间件
const seoMiddleware = new SEOMiddleware({
    templateDir: path.join(__dirname, 'public/seo-templates'),
    debug: true // 开发环境开启调试日志
})

// 应用SEO中间件（必须在静态文件服务之前）
app.use(seoMiddleware.express())

// 静态文件服务
app.use(express.static(path.join(__dirname, 'dist')))

// SPA路由处理
app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, 'dist/index.html'))
})
```

#### 选项B：使用 Nginx

- 天远数据站点：参考 `server/nginx-www.tianyuandb.com.conf`，将 `root` 和 `server_name`、证书路径改为你的服务器路径。
- 幸福查站点：参考 `server/nginx-www.xingfucha.cn.conf`。
- 部署时把 `public/seo-templates/` 整目录上传到服务器 `root` 下的 `seo-templates/`。

```bash
# 复制并修改配置
cp server/nginx-www.tianyuandb.com.conf /etc/nginx/sites-available/zhinengcha
nano /etc/nginx/sites-available/zhinengcha   # 修改 root、证书等

# 启用并重载
ln -s /etc/nginx/sites-available/zhinengcha /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx
```

#### 选项C：使用Koa

```javascript
const Koa = require('koa')
const serve = require('koa-static')
const SEOMiddleware = require('./server/middleware')

const app = new Koa()

// 应用SEO中间件
const seoMiddleware = new SEOMiddleware({
    templateDir: path.join(__dirname, 'public/seo-templates'),
    debug: true
})

app.use(seoMiddleware.koa())

// 静态文件服务
app.use(serve(path.join(__dirname, 'dist')))

app.listen(3000)
```

### 步骤3：测试爬虫检测

```bash
# 模拟百度爬虫
curl -A "Baiduspider" http://localhost:3000/

# 模拟Google爬虫
curl -A "Googlebot/2.1" http://localhost:3000/

# 模拟普通用户
curl http://localhost:3000/
```

## 🔧 配置说明

### 爬虫检测器配置

`crawler-detector.js` 包含以下爬虫识别：

- **中文搜索引擎**：百度、360、搜狗、必应、有道、搜搜、头条搜索
- **国际搜索引擎**：Google、Bing、Yahoo
- **社交媒体爬虫**：Facebook、Twitter、LinkedIn、WhatsApp等

你可以根据需要添加或修改爬虫模式：

```javascript
// 在crawler-detector.js中添加新的爬虫模式
this.crawlerPatterns.push('your-custom-bot')
```

### 路由到模板映射

在 `middleware.js` 中配置路由与模板的对应关系：

```javascript
this.routeTemplateMap = {
    '/': 'index.html',
    '/agent': 'agent.html',
    // 添加新的路由映射
    '/new-route': 'new-template.html'
}
```

### 模板生成配置

**推荐**：页面 SEO 以 `src/composables/useSEO.js` 为唯一来源；修改标题/描述/关键词时只改 `useSEO.js` 中的 `routeConfigs`，然后同步到服务端：

- 在 `server/generate-seo-templates.cjs` 的 `pageSEOConfigs` 中保持与 `useSEO.js` 一致（含新增路由与 `BASE_URL`）。
- 在 `server/middleware.js` 的 `routeTemplateMap` 中为新路由添加映射。
- 若用 Nginx，在对应 conf 的 `$seo_file` 中增加 `if ($uri = '/新路径') { set $seo_file 新模板.html; }`。

新增页面示例（`generate-seo-templates.cjs`）：

```javascript
'new-template.html': {
    title: '页面标题',
    description: '页面描述',
    keywords: '关键词1,关键词2',
    url: 'https://www.tianyuandb.com/new-route'
}
```

## 📝 自定义模板

### 修改模板样式

编辑 `generate-seo-templates.js` 中的 `generateHTMLTemplate` 函数：

```javascript
function generateHTMLTemplate(config) {
    return `<!DOCTYPE html>
    <html>
    <head>
        <!-- 头部信息 -->
        <style>
            /* 自定义样式 */
            body { ... }
        </style>
    </head>
    <body>
        <!-- 自定义内容 -->
    </body>
    </html>`
}
```

### 添加结构化数据

模板已包含基本的结构化数据（JSON-LD格式），如需扩展：

```javascript
const structuredData = {
    "@context": "https://schema.org",
    "@type": "WebPage",
    // 添加更多字段
    "breadcrumb": {
        "@type": "BreadcrumbList",
        "itemListElement": [...]
    }
}
```

## 🧪 验证SEO效果

### 使用在线工具

1. **百度资源平台**：https://ziyuan.baidu.com/
2. **Google Search Console**：https://search.google.com/search-console
3. **必应网站管理员工具**：https://www.bing.com/webmasters

### 使用命令行工具与检测脚本

```bash
# 本地/线上 SEO 检测（会请求爬虫 UA 与普通 UA）
cd server
SEO_TEST_URL=http://localhost:3000 node test-seo.js
# 或线上：SEO_TEST_URL=https://www.tianyuandb.com node test-seo.js
```

```bash
# 查看爬虫看到的标题
curl -s -A "Baiduspider/2.0" https://www.tianyuandb.com/ | grep -o '<title>.*</title>'

# 检查 meta 与 canonical
curl -s -A "Googlebot" https://www.tianyuandb.com/ | grep -E '<meta name="description"|<meta name="keywords"|<link rel="canonical"'

# 检查结构化数据
curl -s -A "Baiduspider" https://www.tianyuandb.com/ | grep -A 20 'application/ld+json'
```

## 📊 维护建议

### 定期更新爬虫列表

搜索引擎爬虫的User-Agent可能会更新，建议定期检查并更新：

- 百度：https://ziyuan.baidu.com/spider/
- Google：https://support.google.com/webmasters/answer/1061943

### 保持模板内容同步

当 `useSEO.js` 中页面 SEO 更新时，重新生成模板并部署：

```bash
cd server
node generate-seo-templates.cjs
# 将 public/seo-templates/ 上传到服务器对应目录
```

可选定时任务（例如每小时同步一次）：

```bash
0 * * * * cd /path/to/tydata-webview-v2/server && node generate-seo-templates.cjs
```

### 监控爬虫访问

在服务器日志中监控爬虫访问情况：

```bash
# 查看百度爬虫访问
grep "Baiduspider" /var/log/nginx/access.log

# 查看Google爬虫访问
grep "Googlebot" /var/log/nginx/access.log
```

## 🐛 常见问题

### Q1: 爬虫访问的是SPA还是静态HTML？

检查响应头：
```bash
curl -I -A "Baiduspider" http://www.xingfucha.cn/
```

若看到 `X-SEOMiddleware: prerendered`（Node 中间件）或 `X-SEOMiddleware: nginx-prerendered`（Nginx），说明返回的是 SEO 静态 HTML。

### Q2: 如何调试爬虫检测？

启用调试模式：
```javascript
const seoMiddleware = new SEOMiddleware({
    templateDir: 'public/seo-templates',
    debug: true // 查看详细日志
})
```

### Q3: 模板内容如何更新？

以 `src/composables/useSEO.js` 为准修改标题/描述/关键词，再在 `server/generate-seo-templates.cjs` 中同步 `pageSEOConfigs`，然后执行：
```bash
node generate-seo-templates.cjs
```

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

静态模板只包含静态内容。如果需要包含动态数据，可以考虑：

1. **预渲染服务**：如 Prerender.io
2. **服务端渲染**：迁移到 Nuxt.js
3. **混合方案**：静态模板 + AJAX加载动态内容

### Q5: 爬虫列表是否会误判？

如果某个用户被误判为爬虫，可以：

1. 检查User-Agent是否包含爬虫关键词
2. 在检测器中添加白名单
3. 使用IP地址作为辅助判断

## 📚 参考资源

- [百度搜索蜘蛛协议](https://ziyuan.baidu.com/spider/)
- [Google 爬虫文档](https://developers.google.com/search/docs/crawling-indexing/overview-google-crawlers)
- [结构化数据规范](https://schema.org/)
- [Open Graph 协议](https://ogp.me/)

## 🆘 支持

如有问题，请检查：

1. 模板目录是否存在：`public/seo-templates/`
2. 模板文件是否生成：运行 `node generate-seo-templates.js`
3. 服务器配置是否正确：检查中间件或Nginx配置
4. 爬虫User-Agent是否匹配：查看检测器日志

## 📄 许可

本方案可自由使用和修改。