跳到主要内容

小程序 downloadFile 域名配置指引

背景说明​

在微信小程序开发中，当需要下载文件时，必须使用官方提供的 wx.downloadFile() API。根据微信小程序的安全规则，该 API 只能访问已在微信公众平台后台配置的域名。本文将指导您如何正确配置 downloadFile 合法域名。

配置步骤​

根据您的小程序与云开发平台的关联方式，有两种不同的配置方法：

方法一：扫码授权关联的小程序​

如果您的小程序是通过扫码授权方式与云开发平台关联的，可以直接在云开发平台进行配置：

  1. 登录腾讯云开发控制台

  2. 进入已授权的小程序环境

    • 在【素材与管理】，找到已授权的小程序

  3. 配置 downloadFile 域名

    • 进入小程序域名配置区域
    • 点击【编辑】按钮
    • 在【downloadFile 合法域名】输入框中添加需要的域名
    • 点击【保存】按钮提交配置

  4. 验证配置

    • 配置完成后，云开发平台会自动将域名同步到微信公众平台
    • 您可以在小程序开发工具中测试下载功能，确认域名配置是否生效

方法二：全托管小程序​

如果您的小程序是全托管方式，需要在微信公众平台手动配置：

  1. 准备工作

    • 需要配置的域名（必须是 HTTPS 域名）
    • 小程序管理员账号和密码

  2. 登录微信公众平台

  3. 进入开发设置页面

    • 在左侧菜单栏【开发与服务】中，点击【开发管理】
    • 在二级菜单中，点击【开发设置】

  4. 配置 downloadFile 合法域名

    • 在开发设置页面，找到【服务器域名】配置区域
    • 在【downloadFile 合法域名】配置项下，点击【修改】按钮
    • 在弹出的窗口中，点击【添加】按钮
    • 输入您需要配置的域名，例如：https://example.com
      • 注意：域名必须包含 https://前缀
    • 点击【确定】保存设置

  5. 验证配置

    • 配置完成后，您可以在小程序开发工具中测试下载功能，确认域名配置是否生效

注意事项​

  • 域名要求：

    • 必须是 HTTPS，HTTP 域名将无法使用
    • 域名不能使用 IP 地址（包括 localhost）
    • 域名必须经过 ICP 备案
    • 域名需要有效的 SSL 证书

  • 配置限制：

    • 每个月只有 5 次修改域名的机会，请谨慎操作
    • 最多可配置 20 个 downloadFile 合法域名

  • 开发调试：

    • 在开发环境中，可以在微信开发者工具中勾选【不校验合法域名】选项进行调试
    • 正式上线前必须完成域名配置

  • 域名生效时间：

    • 域名配置后通常会立即生效
    • 如遇到未生效情况，可尝试重启小程序或清除缓存

常见问题​

1. 配置后仍然无法下载文件​

  • 检查域名是否正确配置，包括 https://前缀
  • 确认域名的 SSL 证书是否有效
  • 检查下载链接是否与配置的域名完全匹配

2. 提示"无法下载，域名不合法"​

  • 确认您使用的下载域名是否已添加到合法域名列表
  • 检查域名格式是否正确，必须包含 https://前缀

3. 扫码授权后在云开发平台配置不生效​

  • 确认小程序授权是否仍然有效
  • 尝试重新授权小程序
  • 检查是否有足够的域名配置次数（每月限制 50 次）