SPA SEO 预渲染改造说明日期2026-08-05状态已验证通过内网renderHtml、官网 Googlebot 模拟、详情页跳转均正常1. 背景与目标官网前端为 Vue SPA。搜索引擎爬虫抓取时若只拿到空壳 HTML中间内容、样式、图片会缺失SEO 效果差。目标通过 Puppeteer 服务将页面渲染成带正文的静态 HTML再由 Nginx 在识别到爬虫 UA 时转发预渲染结果使爬虫能拿到有效内容。相关文件文件作用linuxScreen.jsPuppeteer 预渲染服务/renderHtmlgbcom.conf官网 Nginx爬虫分流与静态资源直连frontend/src/views/*.vue详情入口改为真实链接便于无 JS 与爬虫跟随2. 整体链路爬虫请求 https://www.gbcom.com.cn/xxx │ ▼ Nginx 判断 UA 是否为爬虫 │ ├─ 静态资源 / API → 直连业务服务$myproxy │ └─ HTML 页面 → seo 服务 /renderHtml?url完整地址 │ ▼ Puppeteer 打开原站 URL 等待 Vue API 渲染完成 资源地址绝对化、去掉 SPA 脚本 │ ▼ 返回静态 HTML含正文 / 样式链接 / 真实 a 链接内网自测入口示例http://10.60.2.193:35105/renderHtml?urlhttp://10.60.2.193:456783. 问题与修复过程3.1 样式、图片、JS 加载失败现象预渲染页只有导航/页脚骨架中间大片空白或样式丢失。源码里资源仍是根路径/assets/index-xxxx.js、/assets/index-xxxx.css。浏览器打开的是35105/renderHtml?...会去请求35105/assets/...而真实资源在45678。原因返回 HTML 与资源不在同一源根路径/assets/...解析错主机。曾写死base hrefhttps://www.gbcom.com.cn/与内网测试地址不一致。Vite 资源带crossorigin跨源打开渲染页时 CSS 易被 CORS 拦住。修复linuxScreen.js按请求参数url动态取 origin注入正确base。将src/href/srcset/ 内联url()等改写为绝对地址。去掉crossorigin避免跨源看渲染结果时样式失败。3.2 Navigation timeout60s现象渲染失败: Navigation timeout of 60000 ms exceeded原因使用了waitUntil: networkidle0。SPA 常有轮询/长连接网络很难“完全空闲”Puppeteer 一直等到超时。修复改为domcontentloaded。再等#app、业务内容选择器、软等网络空闲超时不中断。兼容新旧 Puppeteer有则用waitForNetworkIdle无则短延迟。3.3 中间主内容出不来现象头尾正常中间 Banner / 解决方案卡片仍空白。原因首页中间数据来自接口如/api/banner、/api/categories/type/solution截取得太早。解决方案卡片默认opacity: 0需加animate-in才可见。返回 HTML 仍带 SPA 入口脚本浏览器再次执行app.mount(#app)会清空已预渲染的 DOM且在渲染域名下接口常失败。修复等待.home .solution-item或列表卡片 /main正文出现后再取 HTML。强制为.solution-item添加animate-in并滚动触发懒加载。移除页面中的业务 JS保留application/ldjson避免二次水合冲掉预渲染结果。保留 CSS 链接已绝对化保证样式正常。3.4 官网 Googlebot 模拟仍无样式图片 Type 变成 text/html现象直连renderHtml正常在www.gbcom.com.cn下把 UA 设为 Googlebot 后页面裸奔。Network 中.jpg/ 样式等 Status200但 Type 为text/html。原因gbcom.conflocation /里只要 UA 像爬虫所有路径含/assets/*.css、图片都转发到renderHtml静态资源也被渲成 HTML。修复/api/、/assets/、/image/以及常见静态后缀始终走$myproxy。仅 HTML 文档页对爬虫做预渲染。爬虫 UA 匹配收紧为更明确的 bot 名称Googlebot仍可命中。3.5 「查看详情」点不进去现象预渲染列表页能看但点「查看详情」无反应。原因预渲染去掉了 JS原先是button click$router.push(...)没有真实href既不能点击跳转爬虫也跟不到详情页。修复前端将各列表「查看详情」与详情页「返回列表」改为router-link最终为带href的a列表入口HomeView.vue、SolutionsView.vue、ProductsView.vue、ConstructionPlansView.vue、NewsView.vue返回列表NewsDetailView.vue、SolutionDetailView.vue、ProductDetailView.vue、ConstructionPlanDetailView.vue效果无 JS 的预渲染页可正常跳转进详情、回列表。爬虫可沿链接发现详情页并由 Nginx 继续预渲染详情 URL。4. 关键配置要点Nginxwww.gbcom.com.cn443 站点建议结构优先匹配/api/、/assets/、/image/、静态后缀 →proxy_pass $myproxylocation /中仅对爬虫 HTMLproxy_pass http://seo_com_gbcom/renderHtml?url$scheme://$host$request_uri预渲染读超时建议 ≥ 60sPuppeteer 渲染耗时修改后需nginx -t并 reload。5. 预渲染服务要点linuxScreen.js/renderHtml推荐流程goto(url, { waitUntil: domcontentloaded })等待应用挂载与业务 DOM首页卡片 / 列表卡片 / main 正文滚动 强制懒加载图片 animate-in资源绝对化去掉crossorigin删除 SPAscript保留 JSON-LD返回text/html; charsetutf-8自测GET /renderHtml?urlhttp://业务主机:端口/ GET /renderHtml?urlhttp://业务主机:端口/solutions源码中应看到绝对资源地址且不应再包含index-xxxx.js入口脚本中间应有 Banner / 卡片等内容。6. 前端改造要点页面改动首页解决方案卡片整卡router-link详情文案为span.back-button解决方案 / 产品 / 案例列表button→router-link.detail-link新闻列表整卡router-link.news-card新闻 / 方案 / 产品 / 案例详情「返回列表」button→router-link带真实列表href样式上为a补充text-decoration: none、color: inherit等保持原按钮观感。部署重新构建并发布前端后预渲染抓到的 HTML 才会带上真实href。7. 验证清单内网renderHtml?url...首页样式、Banner、解决方案卡片正常官网 Googlebot UACSS/图片 Type 正确不再是text/html预渲染列表页「查看详情」可进入详情普通浏览器 UA 访问官网仍走原 SPA体验不受影响建议自测步骤Chrome DevTools → Network conditions → User agent GooglebotDisable cache。打开首页 / 解决方案列表确认版式与图片正常。点击「查看详情」确认进入详情页且内容完整。Network 中确认.css/ 图片请求直连业务而非再次进入renderHtml。8. 注意事项预渲染页刻意无业务 JS用于 SEO 静态快照用户日常浏览仍走未剥脚本的原站。静态路径变更时Nginx 需同步排除如新的上传目录避免再被预渲染吞掉。勿对爬虫全站无差别代理只代理 HTMLAPI/静态必须直连。详情、分类等路由依赖真实a href新增列表入口请继续用router-link/a不要只用click。等待策略避免networkidle0按业务选择器等待更稳。9. 结论本次改造打通了「Puppeteer 预渲染 Nginx 爬虫分流 前端真实链接」完整链路预渲染 HTML 资源地址正确、正文可见官网爬虫流量下静态资源不再被误渲成 HTML详情入口对无 JS 环境与搜索引擎均可跟随。当前方案已在内网与官网 Googlebot 模拟场景验证通过可用于生产 SEO 使用。