第 8 课：RFQ、SEO、测试与手机端验收

1. 这一节解决什么问题

静态企业站最常见的假完成是：表单显示成功但没人收件；SEO 只改首页标题；手机能缩小显示却无法填写。本节把询盘、搜索、无障碍、异常和真实收信整合为可重复验收。

2. 学完要拿到什么结果

• 一套字段清晰、含隐私同意与反垃圾字段的 RFQ。
• Web3Forms 可配置收信方案和未配置/失败/成功状态。
• 每页标题、描述、canonical、hreflang、robots 与 sitemap。
• 自动检查、构建和路由冒烟结果。
• 375px 手机完成一次真实测试询盘的证据。

3. 对应的开源对标及链接

• Web3Forms 官方 API：浏览器向 https://api.web3forms.com/submit POST，access_key 必填，并处理 200、400、429、500。
• export-website-template：仅研究无后端表单与 SEO 文件；不复用其硬编码访问密钥。
• Web Dev For Beginners accessibility：参考语义、键盘和表单可访问性。

4. 完整图文课程正文

4.1 RFQ 与普通联系表的区别

联系表只问姓名、邮箱、留言，供应方仍要来回追问。RFQ 应收集能准备报价的最小字段：姓名、公司、国家/地区、邮箱、WhatsApp（可选）、产品、预计数量和单位、尺寸/等级、包装、贸易术语、目的港、期望时间、补充要求、隐私同意。

字段过多会降低完成率，因此尺寸、包装和贸易术语可以选择“不确定，需要建议”。不要要求买家上传证件或敏感文件。

4.2 真实接收链路

sequenceDiagram
  participant B as 买家浏览器
  participant W as Web3Forms API
  participant E as 企业收件邮箱
  B->>B: 校验必填、邮箱、数量与同意
  B->>W: POST 字段 + 环境变量 access_key
  W-->>B: success / error / rate limit
  W->>E: 转发结构化询盘邮件
  B->>B: 成功提示或可操作的失败提示

Web3Forms Access Key 会出现在浏览器请求中，这是该服务的预期用法，但仍应通过环境变量注入、限制来源并启用 botcheck；它不是邮箱密码。绝不能把邮箱密码、服务端 API Secret 写进前端。

当 Key 未配置时，示范站不伪装成功：显示“表单服务未配置”，保留邮件和 WhatsApp 备选入口。发布验收必须使用测试邮箱实际收件并检查字段。

4.3 SEO 是每页可理解

每个路由需要唯一 title、description、canonical 与中英文 alternate。页面只有一个 H1，标题顺序合理；产品详情有真实可见文本，不用关键词堆砌。robots.txt 声明抓取规则和 sitemap；sitemap.xml 列出全部公开中英文 URL。演示域名必须通过 VITE_SITE_URL 替换后再发布。

4.4 手机与无障碍

在 375px 宽度用键盘/触摸完成：打开菜单、切换语言、进产品、打开 FAQ、填写并提交 RFQ。标签不能只靠 placeholder；错误紧邻字段并可被读屏识别；发送按钮在加载时禁用并保留文本；成功后焦点移到状态提示。邮件和 WhatsApp 链接必须显示用途。

4.5 测试分层

• 静态检查：TypeScript 与项目检查命令。
• 构建：确保生产包生成。
• 路由冒烟：本地预览直接请求每个 URL 都返回页面。
• 交互验收：菜单、语言、FAQ、产品预填、错误和成功。
• 内容审核：示例标记、无虚构声明、联系方式和条款。
• 真链路：测试邮箱收到 RFQ，回复地址正确，垃圾箱也检查。

5. 零基础用户能够执行的操作步骤

1. 打开RFQ 字段表，确认必填、类型、验证、邮件字段名和隐私目的。
2. 在 Web3Forms 用测试收件邮箱创建 Access Key，并按服务提示验证邮箱。
3. 复制 .env.example 为 .env.local，填写 VITE_WEB3FORMS_ACCESS_KEY、VITE_CONTACT_EMAIL、VITE_WHATSAPP_NUMBER、VITE_SITE_URL；不要提交该文件。
4. 重启开发服务，使 Vite 读取环境变量。
5. 先提交空表验证前端错误，再填合法值；检查发送中、成功和错误状态。
6. 打开测试邮箱，核对 subject、reply-to 与全部 RFQ 字段；保存脱敏截图或记录编号。
7. 暂时填错 Key，确认页面显示可操作错误且邮件/WhatsApp 备选仍可用；测试后恢复。
8. 填写SEO 检查表和内容审核清单。
9. 运行 npm run check 与 npm run build，再运行项目 README 的预览/路由检查。
10. 用浏览器设备模拟 375px 完成整条路径，不只缩放截图。

6. 可直接复制给 TRAE 或其他 AI 的提示词

请实现 RFQ 的真实可配置提交。先阅读 #File:src/components/RFQForm.tsx、#File:.env.example、#File:../../templates/18-rfq-field-list.md 和 #Rule:项目规则。
要求：
- 只从 import.meta.env.VITE_WEB3FORMS_ACCESS_KEY 读取 Key，不在源码写值；
- POST https://api.web3forms.com/submit，携带 access_key、subject、from_name、replyto、botcheck 和所有 RFQ 字段；
- 客户端验证必填、邮箱、正数数量和隐私同意；
- 状态：未配置、空闲、发送中、成功、400 类错误、429 限流、网络/500 错误；
- 失败不清空表单，成功才清空；状态使用 aria-live；
- 保留 mailto 与 WhatsApp 备选；
- 不上传文件，不收集敏感证件。
完成后运行 check/build，说明如何用测试邮箱做端到端验收。不要声称未实际执行的收信测试通过。

7. 云南大蒜项目中的具体示范

测试询盘使用明确的测试标记：

邮件主题必须含 [TEST] 或明确测试内容，避免业务人员误当真实询盘。验收记录只保存发送时间、结果、字段完整性和脱敏截图，不公开 Access Key。

8. 可填写模板

RFQ 真链路记录：

9. 常见错误

• 把 Access Key 写在组件常量中，或把 .env.local 提交 Git。
• API 失败也显示“提交成功”。
• 只测试正常路径，不测试空字段、限流、断网和未配置。
• SEO 所有页面共用同一个 title，sitemap 仍是示例域名。
• 手机键盘弹出后按钮被遮挡，错误只能靠红色表示。

10. 排错方法

未收件时依次检查：前端 Network 是否发出请求、HTTP 状态和响应正文、Key 是否属于正确邮箱、服务的域名限制、垃圾箱和邮件规则。429 表示限流，不循环重试；给用户稍后再试和备选联系。SEO 不更新时检查路由切换是否调用元信息组件、canonical 是否基于正确站点 URL。手机横向滚动用开发者工具逐个检查超宽元素。

11. 完成标准

• 有效配置后测试邮箱真实收到一封结构化测试 RFQ。

• 未配置、验证失败、发送中、成功、限流和网络失败状态可区分。

• Key 未写死，.env.local 被 Git 忽略。

• 每个路由有唯一元信息与中英文 alternate；robots、sitemap 存在。

• 375px 可完整提交，键盘、标签、错误和 aria-live 可用。

• 内容审核无虚构资质、客户评价和未确认商业数字。

12. 本节成果如何进入下一节

下一节把已通过本地和真链路测试的同一提交部署到公网，配置环境变量、SPA 重写、域名和 HTTPS，再从外网重新执行一次 RFQ 与页面验收。

---

上一节：第 7 课：用 TRAE 分里程碑开发云南大蒜 B2B 网站
下一节：第 9 课：域名、免费部署与真实发布验收