H5 电子名片开发复盘总结

项目背景：制作一个县长电子名片 H5 页面，包含图文展示及“一键保存到通讯录”功能。

核心难点：vCard 兼容性、腾讯云 COS 的访问限制、域名 DNS 配置。

一、 核心技术方案对比

在本次开发中，我们先后尝试了两种主流的 Serverless/云原生 部署方式。

1. 边缘函数 (Edge Functions)

场景：最初尝试。

原理：将 HTML 代码作为字符串，嵌入到 JS 函数中。用户访问时，函数动态生成并返回 HTML。

2. 静态网站托管 (Static Website Hosting) —— 🏆 最终方案

场景：最终采用。

原理：将 index.html 和图片直接上传到对象存储（COS），开启“网站模式”。

二、 关键问题与解决方案 (SOP)

1. 电子名片 (vCard) 兼容性玄学

代码生成的 .vcf 文件在安卓上正常，但在 iOS 上无法导入或乱码。

• 换行符陷阱：编辑器自动格式化会把 \n 转换成物理换行，导致 JS 报错。

  • ✅ 解法：使用 String.fromCharCode(10) 代替 \n 进行拼接。

• iOS 强制要求：

  • 必须包含结构化名字字段：N;CHARSET=UTF-8:姓;名;;;

  • 必须显式声明编码：CHARSET=UTF-8

• 微信拦截：微信内置浏览器拦截下载。

  • ✅ 解法：判断 UserAgent，弹窗提示用户“点击右上角在浏览器打开”。

2. 腾讯云 COS 配置三部曲

这是导致“403 Forbidden”或“强制下载”的核心原因。

1. 开权限：

   • 存储桶默认是“私有读写”。

   • ✅ 操作：权限管理 -> 更改为 “公有读私有写”。

2. 开服务：

   • 默认不开启网站功能。

   • ✅ 操作：基础配置 -> 静态网站 -> 开启 -> 索引文档填 index.html。

3. 避限速：

   • 默认域名被限制预览。

   • ✅ 操作：必须绑定 自定义源站域名（已备案）。

3. DNS 与 CDN (EdgeOne) 的回源陷阱

配置了域名，但访问报错 <Code>NoSuchKey</Code>，提示找不到文件。

• 原因：CNAME 指向了 存储桶物理接口 (.cos.)，而非 网站接口 (.cos-website.)。

  • 物理接口：不懂“访问目录自动找 index.html”的规则。

  • 网站接口：懂得自动索引。

• EdgeOne 干扰：即使 CNAME 写对了，EdgeOne 开启加速后，可能会自作聪明地用内部 API 去拉取数据（相当于走了物理接口）。

  • ✅ 解法：在 EdgeOne/CDN 配置中，强制设置 “回源 Host” 为静态网站的长域名 (...cos-website...)，或者关闭加速仅做 DNS 解析。

4. URL 尾部斜杠 /

• 访问 .../card/dxb ❌ -> 找名为 dxb 的文件 -> 404。

• 访问 .../card/dxb/ ✅ -> 找 dxb 目录下的 index.html -> 200 OK。

三、 下次开发的“黄金路径”

如果下次还要发布 H5 页面，直接按这个步骤走，5分钟搞定：

1. 本地开发：写好 HTML，本地浏览器测试无误。

2. COS 上传：

   • 新建目录（如 /project/v1/）。

   • 上传 index.html 和图片。

3. 开启静态网站：

   • COS 后台 -> 基础配置 -> 静态网站 -> 开启。

4. 配置域名 (最关键)：

   • DNS 解析 CNAME 指向：BucketName.cos-website.Region.myqcloud.com (注意是 cos-website)。

   • 或者在 CDN/EdgeOne 中绑定域名，并设置回源 Host 为上述地址。

5. 发布：

   • 生成二维码时，URL 末尾务必带上 /。