Tolan/项目文档/微信JSSDK错误排查与解决方案.md

微信JSSDK错误排查与解决方案

🔴 当前错误

在微信中打开 https://www.chengyantek.cn/share 时出现以下错误：

{"realAuthUrl":["https://www.chengyantek.cn/share"],"errMsg":"config:invalid url domain"}
{"retCode":-1,"errMsg":"updateAppMessageShareData:the permission value is offline verifying"}

---

⚠️ 重要前提

必须使用微信公众平台

关键点：

• ❌ 微信开放平台的网站应用无法使用JSSDK
• ✅ 必须在微信公众平台注册公众号才能使用JSSDK

如果你只有开放平台的网站应用：

• 无法使用JSSDK分享功能
• 需要注册公众号（订阅号或服务号）
• 或使用替代方案（二维码、复制链接）

详细说明：请查看 微信公众平台与开放平台区别说明

---

📋 错误分析

错误1: config:invalid url domain

含义：JS接口安全域名未配置或配置错误

原因：

• 微信公众平台未配置JS接口安全域名
• 域名格式错误（包含协议、端口或路径）
• 验证文件未正确上传

错误2: updateAppMessageShareData:the permission value is offline verifying

含义：接口权限正在审核中

原因：

• JS接口安全域名配置后，需要等待微信审核（通常几分钟到几小时）
• 审核期间接口权限状态为"离线验证中"

---

✅ 解决方案

步骤0: 确认是否有公众号（重要）

如果你只有开放平台的网站应用：

• ❌ 无法使用JSSDK
• ✅ 需要先注册公众号（订阅号或服务号）
• ✅ 或使用替代方案（二维码、复制链接）

注册公众号步骤：

1. 访问：https://mp.weixin.qq.com
2. 选择"订阅号"（个人可注册，免费）
3. 完成注册（通常几分钟）
4. 获取AppID和AppSecret

详细说明：请查看 微信公众平台与开放平台区别说明

---

步骤1: 配置JS接口安全域名

1.1 登录微信公众平台

访问：https://mp.weixin.qq.com

⚠️ 注意：必须是微信公众平台，不是微信开放平台！

1.2 进入配置页面

路径：

设置与开发 → 公众号设置 → 功能设置 → JS接口安全域名

⚠️ 重要：不是"授权回调域"，也不是"业务域名"！

1.3 添加域名

配置格式：

• ✅ 正确：www.chengyantek.cn（只填域名，不带协议、端口、路径）
• ❌ 错误：https://www.chengyantek.cn
• ❌ 错误：www.chengyantek.cn:443
• ❌ 错误：www.chengyantek.cn/share

操作步骤：

1. 点击 设置 或 添加 按钮
2. 输入域名：www.chengyantek.cn
3. 点击 确定
4. 下载验证文件（文件名类似 MP_verify_xxxxxxxx.txt）

1.4 上传验证文件

文件路径：

https://www.chengyantek.cn/MP_verify_xxxxxxxx.txt

上传方法：

1. 将验证文件上传到服务器根目录（/）
2. 确保可以通过 https://www.chengyantek.cn/MP_verify_xxxxxxxx.txt 访问
3. 在微信公众平台点击 确认

验证方法：

# 测试验证文件是否可以访问
curl https://www.chengyantek.cn/MP_verify_xxxxxxxx.txt

应该返回验证文件内容（一串字符）。

---

步骤2: 等待审核

2.1 审核时间

• 通常：几分钟到几小时
• 最长：24小时内

2.2 审核状态检查

方法1：查看配置页面

• 进入：公众号设置 → 功能设置 → JS接口安全域名
• 查看域名状态：
  • ✅ 已生效：显示"已配置"
  • ⏳ 审核中：显示"审核中"或"离线验证中"

方法2：在微信中测试

• 手机微信打开：https://www.chengyantek.cn/share
• 打开微信调试工具（右上角 ⋯ → 反馈与帮助 → 工具 → 微信网页调试）
• 查看控制台：
  • ✅ 成功：config:ok
  • ❌ 失败：config:invalid url domain 或 the permission value is offline verifying

---

步骤3: 验证配置

3.1 测试后端配置接口

curl "https://www.chengyantek.cn/api/wechat/jsapi/config?url=https://www.chengyantek.cn/share"

预期返回：

{
  "success": true,
  "data": {
    "appId": "wx...",
    "timestamp": 1234567890,
    "nonceStr": "abc123",
    "signature": "d4f5e6..."
  }
}

3.2 在微信中测试

1. 手机微信打开：https://www.chengyantek.cn/share
2. 打开调试工具：
   • 右上角 ⋯ → 反馈与帮助 → 工具 → 微信网页调试
3. 查看控制台输出：
   • ✅ config:ok - 配置成功
   • ✅ updateAppMessageShareData:ok - 分享接口可用
   • ❌ config:invalid url domain - 域名未配置
   • ❌ the permission value is offline verifying - 审核中

---

🔍 常见问题

Q1: 配置后仍然报错？

可能原因：

1. 验证文件未正确上传
2. 域名格式错误（包含协议或路径）
3. 配置未生效（等待几分钟后重试）
4. 使用了错误的AppID（服务号/订阅号/小程序AppID不同）
5. 使用了开放平台的AppID（错误！）

解决方法：

1. 检查验证文件是否可以访问
2. 确认域名格式正确（只填域名）
3. 清除微信缓存，重新打开页面
4. 确认使用的是公众号AppID（公众平台），不是小程序AppID，也不是开放平台的AppID
5. 确认已在公众平台注册公众号，不是只有开放平台的网站应用

Q0: 我只有开放平台的网站应用，可以使用JSSDK吗？

答案：❌ 不可以！

原因：

• JSSDK是微信公众平台的功能
• 开放平台的网站应用不支持JSSDK
• 必须注册公众号（订阅号或服务号）才能使用JSSDK

解决方案：

1. 注册公众号（订阅号免费，个人可申请）
2. 或使用替代方案（二维码、复制链接）

详细说明：请查看 微信公众平台与开放平台区别说明

Q2: 需要配置多个域名？

支持配置：

• 最多可以配置 3个域名
• 每个域名都需要单独上传验证文件

示例：

www.chengyantek.cn
m.chengyantek.cn
api.chengyantek.cn

Q3: 子域名需要单独配置吗？

需要！每个子域名都需要单独配置。

示例：

• www.chengyantek.cn → 需要配置
• m.chengyantek.cn → 需要单独配置
• api.chengyantek.cn → 需要单独配置

Q4: 审核需要多长时间？

通常：

• 几分钟到几小时
• 最长24小时

如果超过24小时仍未生效：

1. 检查验证文件是否正确上传
2. 检查域名格式是否正确
3. 联系微信客服

---

📊 配置检查清单

• 已登录微信公众平台
• 已进入"功能设置" → "JS接口安全域名"
• 已添加域名：www.chengyantek.cn（不含协议）
• 已下载验证文件
• 已上传验证文件到服务器根目录
• 验证文件可以访问：https://www.chengyantek.cn/MP_verify_xxx.txt
• 已在微信公众平台点击"确认"
• 已等待审核（几分钟到几小时）
• 已在微信中测试，显示 config:ok
• 分享功能正常工作

---

🚀 快速修复步骤

立即执行

1. 登录微信公众平台

   https://mp.weixin.qq.com
   

2. 进入配置页面

   设置与开发 → 公众号设置 → 功能设置 → JS接口安全域名
   

3. 添加域名

   输入：www.chengyantek.cn
   （不要包含 https:// 和 /share）
   

4. 上传验证文件

   下载验证文件 → 上传到服务器根目录 → 确认
   

5. 等待审核

   通常几分钟到几小时，最长24小时
   

6. 测试

   手机微信打开：https://www.chengyantek.cn/share
   查看是否显示 config:ok
   

---

📚 相关文档

文档	说明
微信JS接口安全域名配置指南	详细配置步骤
微信JSSDK分享测试指南	测试方法
微信分享环境变量配置	后端配置说明

---

✅ 总结

1. JS接口安全域名 是独立的配置项，必须单独配置
2. 格式要求：只填域名，不带协议、端口、路径
3. 你的正确配置：www.chengyantek.cn
4. 配置位置：公众号设置 → 功能设置 → JS接口安全域名
5. 需要验证文件：上传到服务器根目录并确认
6. 需要等待审核：通常几分钟到几小时

配置完成后，等待审核通过，错误应该会消失！🎉