最近在小程序开发群里看到好几个类似的问题都是被wx.downloadFile的合法域名配置搞到头大。其中下载图片/文件一直 fail报 url not in domain list或者是后台配置域名时填了带路径的地址结果死活不生效更常见的是一堆人问filepath 到底要不要写进域名里。说白了这类问题的根源基本都指向一件事微信小程序的 downloadFile 合法域名根本不允许带路径而且业务代码里出现的filePath、URL 参数里的filepath、域名里的路径这三样东西太容易被混为一谈。这篇文章我就围绕这个标题把我处理过的同类问题完整拆一遍从配置规则、报错解读、调用链路排查到最常见的去掉 filepath 后一切正常的实战场景一次讲透。1. 微信后台域名配置规则为什么带路径必翻车1.1 合法域名到底校验的是什么微信小程序所有网络相关接口在非调试环境下都会做域名合法性校验。wx.downloadFile对应的是后台开发管理-开发设置-服务器域名里的downloadFile 合法域名。这里的校验逻辑非常直白它只校验https://协议 域名含端口这一层路径部分会被忽略或者说带了路径就是不符合格式要求。很多人搞不明白这一点是因为在浏览器里访问一个完整 URL 习惯了比如https://example.com/files/report.pdf觉得填域名的时候也应该把/files/report.pdf一起填进去。实际上后台配置域名时正确的格式只能是https://example.com如果你填成https://example.com/files这个配置在小程序后台大概率会提示域名格式不正确即便侥幸保存成功wx.downloadFile在真机上依然会报url not in domain list。原因很简单微信后台的域名格式校验要求不能包含路径它会校验https://后面的部分必须以域名或 IP 加可选端口结尾不允许出现/之后的路径字符。1.2 一个典型案例填了完整文件地址后下载必失败打个比方某公司给客户做一个内部资料下载的小程序后端返回的文件地址是https://api.somecompany.cn/download/2024/12/123456.pdf。负责配置的同学想省事直接在 downloadFile 合法域名里填了https://api.somecompany.cn/download觉得这样总该匹配到了吧。结果真机一测wx.downloadFile直接 fail报错信息就是经典的downloadFile:fail url not in domain list这个情况的坑点在于开发者工具里如果勾选了不校验合法域名本地调试完全正常一旦手机上打开就是报错。后台配置的域名虽然能保存成功某些情况下微信后台对带路径的格式并不做严格拒绝但校验时不认但实际校验时依然按域名为主路径根本不在匹配范围内于是请求被拦截。1.3 正确的配置姿势正确的做法是在 downloadFile 合法域名里填https://api.somecompany.cn后面的/download/2024/12/123456.pdf不需要管也不用填请求发出时微信只拿https://api.somecompany.cn去比对域名列表。只要域名匹配、备案有效、HTTPS 证书没问题文件下载就不会因为域名问题被拦。这里要额外提一个容易踩的坑如果你用了对象存储的自定义域名比如 CDN 域名是https://cdn.somecompany.cn但接口返回的文件 URL 是https://api.somecompany.cn/download/...这种由后端转发的方式那么 downloadFile 合法域名只需要配置https://api.somecompany.cn。如果文件直链是https://cdn.somecompany.cn/xxx/yyy.pdf那就要把https://cdn.somecompany.cn也加进合法域名列表。这条规则特别容易和 request 合法域名搞混很多人把域名都配在 request 里到了 downloadFile 时报错才想起来还有一个单独的域名列表。2. wx.downloadFile 的三层域名校验关卡2.1 第一关开发者工具里的不校验开关微信开发者工具默认不会拦截未配置的域名因为本地调试阶段你不可能每次都去后台改域名。详情面板 - 本地设置 - 勾选不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书勾上之后任何域名都能请求wx.downloadFile在模拟器和真机调试模式下基本畅通无阻。但注意真机调试和真机预览是两个概念。真机调试有调试模式加持域名校验会被绕过真机预览有时候也会弹出一个开启调试的按钮点开之后同样能绕过校验。这也是为什么很多开发者在预览阶段觉得没问题了结果正式版一上线全挂。2.2 第二关体验版与正式版的硬校验体验版和正式版没有任何开关可以绕过域名校验才会老老实实走后台配置的 downloadFile 合法域名。在这个阶段所有 URL 都会拿去比对一旦不匹配就 fail。我接手过一个模拟项目体验版下载 PDF 一直失败原因就是合法域名只配了https://a.somecompany.cn但代码里实际请求的是https://b.somecompany.cn/download/...。这个可以从报错日志里看得很清楚域名都不在一个列表里自然被拦截。2.3 第三关证书与备案的隐性拦路虎除了域名列表匹配微信还会校验 HTTPS 证书是否有效、域名是否 ICP 备案。这个问题通常是历史遗留的公司用了某个很久没续费的域名证书过期或者域名备案掉了。这时报错可能是:downloadFile:fail 无法连接到服务器或者干脆是网络层失败看起来跟域名配置无关实际是通信层被卡住。排查的时候如果域名已经配了、格式也对就要怀疑证书和备案这两个隐性条件。我给一个非常实用的自检顺序域名列表里有没有这个域名域名后面有没有不小心带了路径这个域名能不能在浏览器里直接打开并触发下载证书链是否完整用浏览器访问一下看地址栏的小锁域名备案有没有掉通常访问时会提示该网站无法访问或未备案只要这五步都过了wx.downloadFile的域名相关问题基本就排干净了。3. 被反复误会的 filepath三种含义必须分清3.1 地址参数里的 filepath很多业务系统的文件接口长这样https://api.somecompany.cn/getFile?filepath/uploads/report_2024_12.pdf这里的filepath是一个业务参数名由后端定义用来告诉服务器想拿哪个文件。它跟微信小程序的合法域名没有任何直接关系。域名校验时只关心https://api.somecompany.cn是否在列表里参数部分完全不影响匹配。但这个场景下容易出现一个隐蔽问题如果你的下载地址是后端动态拼接的而filepath参数里又带了某些特殊字符比如中文、空格、#后端返回的 URL 没有做encodeURIComponent那么wx.downloadFile请求时有可能因为 URL 格式问题导致下载失败。这类问题处理方式很简单前端在拿到 URL 后对参数部分做一次编码const baseUrl https://api.somecompany.cn/getFile; const filepath /uploads/report 2024_12.pdf; const fullUrl ${baseUrl}?filepath${encodeURIComponent(filepath)}; wx.downloadFile({ url: fullUrl, success(res) { // ... } });需要注意的是wx.downloadFile的 URL 本身会被微信做一次合法性校验但它不会替你编码参数所以参数里如果有空格或其他特殊字符最好自己先编码好。否则在某些机型上会表现成時好時坏有时候能下载有时候 fail。3.2 域名配置里的路径段真正要去掉的 filepath回到标题去掉 filepath最核心的含义在配置 downloadFile 合法域名时不能把文件路径或接口路径写进去。举个例子你有一个文件服务的完整地址是https://file.somecompany.cn/path/to/file.pdf在做后台配置时只需要https://file.somecompany.cn/path/to/file.pdf这一段必须去掉。同样如果接口地址是https://api.somecompany.cn/download/file配置域名时也是https://api.somecompany.cn后面那个/download/file不写。如果已经配错了比如后台填了https://file.somecompany.cn/path那么即使前端代码里的 URL 是完整的https://file.somecompany.cn/path/to/file.pdf微信依然会判定域名不匹配。因为校验逻辑拿的是https://file.somecompany.cn和配置里的https://file.somecompany.cn/path比两者不相等直接 fail。我在实际处理中见过最迷惑的操作是把 URL 里的filepath参数名改动去掉比如有人把https://file.somecompany.cn/download?filepath/a.pdf改成了https://file.somecompany.cn/download?url/a.pdf然后以为问题解决了。实际上域名校验从来没管过参数名这样改没有任何意义真正要改的是后台配置里不能出现路径段。3.3 下载保存路径 filePath这是结果不是原因wx.downloadFile成功回调里会返回一个tempFilePath这是临时文件路径。如果你需要把文件保存到本地通常会配合wx.saveFile或wx.openDocument使用这时才会涉及一个叫filePath的概念。但很多人会陷入一个误区以为下载失败是因为没有传filePath然后去wx.downloadFile的url里手动加了一个filepath参数想指定文件路径。这完全不对。wx.downloadFile只需要一个url其他都是可选配置。加不加filepath参数、参数叫什么跟能不能下载成功没有关系唯一的域名校验只认 URL 的协议、域名和端口。wx.downloadFile({ url: https://api.somecompany.cn/download/123456.pdf, success(res) { if (res.statusCode 200) { // res.tempFilePath 就是临时路径不是通过参数传进去的 console.log(res.tempFilePath); } } });这个tempFilePath是系统帮你生成的不是你在调用前传入的。所以如果有人跟你讨论去掉 filepath你要先搞清楚他说的到底是哪一个filepath否则很容易南辕北辙。4. 一次真实的下载失败排查从报错到修复的完整链路4.1 报错信息现场还原模拟项目里出现过这样一次事故。同事在小程序里接了一个下载合同文件的功能本地开发者工具一切正常体验版一测就挂。把报错信息抓出来是downloadFile:fail url not in domain list看一眼后端返回的下载地址https://api.somecompany.cn/contract/download?filepath/contracts/2024/11/abc.pdf再打开小程序后台的 downloadFile 合法域名里面配的是这些https://api.somecompany.cn/contract/download https://api.somecompany.cn这里最大的问题不是域名有没有配而是配了一个带路径的地址。微信后台保存这个配置时大概率会提示格式问题即便保存成功校验逻辑也不认。看到这个配置基本可以断定https://api.somecompany.cn/contract/download这个条目是多余的甚至可能因为格式非法导致整个列表的校验异常。4.2 逐步排查链路遇到url not in domain list我的排查链路是这样的第一步看代码里wx.downloadFile的url到底是什么。把 url 打出来确认协议、域名、端口、路径段。第二步看后台域名列表是否包含这个域名。只看域名部分把https://和后面的/path拆开。比如上面这个例子只需要确认https://api.somecompany.cn在列表里即可。第三步检查后台配置里有没有多余的带路径条目。如果发现https://api.somecompany.cn/contract/download这种立刻删掉重新填https://api.somecompany.cn。删掉之后等几分钟让配置生效。第四步验证 URL 参数是否影响匹配。把?filepath/contracts/2024/11/abc.pdf从 URL 里拆出来或者在前端用一个固定的无参数地址https://api.somecompany.cn/contract/download测试看是否还报同样的错。如果无参数地址能通说明就是域名配置的问题。第五步换真机验证。很多人容易在开发者工具里自我欺骗一定要用体验版二维码在真机上测最好是在 iOS 和 Android 各测一遍因为某些老旧的安卓 WebView 对 URL 编码的容忍度不同可能会额外暴露参数编码问题。4.3 修复操作与验证结果这个案例的修复动作其实很简单登录小程序后台进入 downloadFile 合法域名列表。把https://api.somecompany.cn/contract/download删掉。确认https://api.somecompany.cn在列表里。保存后等待几分钟。重新编译体验版真机测试下载。修复后代码不用动wx.downloadFile的地址依然是https://api.somecompany.cn/contract/download?filepath/contracts/2024/11/abc.pdf下载恢复正常。因为域名校验只匹配协议、域名和端口路径和参数不影响。类似的坑还有另一种变体域名填对了但wx.downloadFile的 url 带了端口比如https://api.somecompany.cn:8443/...而域名列表里只配了https://api.somecompany.cn没有端口。微信的规则是如果 URL 里带了非默认端口域名列表里也需要配置对应的端口。默认情况下 HTTPS 端口是 443可以不用写但如果是 8443 这种就必须在后台配置https://api.somecompany.cn:8443否则照样not in domain list。这两种情况并列在一起基本上覆盖了 downloadFile 域名配置里最常见的两个拦路虎路径和端口。5. 从去掉 filepath延伸出来的项目级建议5.1 统一接口规范让 URL 里的路径和参数名不再制造混乱标题里的去掉 filepath往深处走其实是一个接口规范问题。很多项目下载文件的 URL 是后端直接拼的参数名一会儿叫filepath一会儿叫fileName一会儿又是path。这种随意性会导致排查成本居高不下。我的建议是小程序项目里所有下载类接口统一走一个下载网关https://api.somecompany.cn/download?fileIdxxxxx后端根据fileId找到真实存储路径再决定是走转发还是重定向到对象存储。前端永远只拿fileId不感知文件物理路径。这样做有几个好处域名列表只需要配置https://api.somecompany.cn一个域名文件存储后端可以随意迁移换 CDN、换存储桶小程序端不用改前端不会因为filepath参数里出现#、空格、中文等特殊字符而踩 URL 编码的坑权限校验可以放在下载网关层比直接暴露文件地址安全得多如果你们项目已经是完整文件地址 路径参数的模式强制要求后端返回的 URL 必须做过encodeURIComponent并且路径参数名统一最好在接口文档里约定为fileId或fileKey不要再叫filepath从命名上减少误解。5.2 前端调用层的防御式写法即使理论上域名配置对了前端也应该写一段防御式逻辑避免用户在弱网或异常情况下被下载失败四个字劝退。function downloadFile(url) { return new Promise((resolve, reject) { wx.downloadFile({ url, timeout: 30000, success(res) { if (res.statusCode 200) { resolve(res.tempFilePath); } else { reject(new Error(下载失败HTTP 状态码${res.statusCode})); } }, fail(err) { // 把 err.errMsg 打出来辅助定位 console.error(downloadFile fail, err.errMsg); reject(err); } }); }); }timeout参数很关键不设的话某些低端机会长时间卡住用户会以为小程序死了。实测下来 iOS 上 30 秒是一个比较稳的阈值再长对用户来说就没耐心了。下载成功后的临时文件如果需要长期保存尽早调用wx.saveFile因为临时文件在小程序退出后可能被清理。wx.saveFile的filePath参数是可选的不传就自动生成所以不要纠结于要不要去掉 filepath这类问题保存逻辑本来就跟你传不传无关。5.3 一个容易漏掉的细节域名配置生效时间微信后台的域名配置保存后并不是秒级生效。我以前也踩过这个坑保存完立刻去真机测还是报url not in domain list就以为配置方法不对反反复复试了十几次。后来才知道域名配置有几分钟到十几分钟的缓存时间。所以在你修改完 downloadFile 合法域名之后不要马上测试等 5 到 10 分钟再试。如果修改完还是报原来的错优先排查是不是缓存没刷而不是马上怀疑配置格式。另外downloadFile和request的合法域名是独立的两个列表改了downloadFile不会影响request反之亦然。有时候你发现wx.request能通但wx.downloadFile不行往往就是因为只配了 request 域名忘了配 downloadFile 域名。这两个列表虽然字段长得一样但互不相通必须分别配置。5.4 下载文件保存后的打开姿势如果是下载 PDF、Word 之类的文档保存完成后要打开用wx.openDocument。这里也有一个常见误区有些人以为wx.openDocument也需要配置域名其实不用它读取的是本地文件路径完全不涉及网络请求。真正需要域名配置的只有下载那一步。wx.saveFile({ tempFilePath: res.tempFilePath, success(saveRes) { wx.openDocument({ filePath: saveRes.savedFilePath, fileType: pdf, showMenu: true, success() { // 打开成功 } }); } });showMenu这个参数我建议设成true这样用户打开文件后右上角能弹出菜单可以转发、收藏、保存到通讯录之类的。如果不设置很多机型上的文档页面只是一个纯阅读页没法做后续操作体验上会差不少。5.5 项目上线前的域名自查清单我的习惯是在每次发布正式版之前把域名相关的几项全部过一遍。查完这几项downloadFile 域名问题基本不会带病上线检查项预期结果常见错误downloadFile 合法域名是否已配置包含所有实际使用的下载域名只配了 request 域名域名是否带路径不带只有协议 域名 可选端口填了/download等路径HTTPS 证书有效性浏览器访问正常无安全警告证书过期或链不完整域名是否 ICP 备案备案在有效期内备案掉了或新域名未备案URL 参数是否已编码无中文、空格、#等裸参数后端直接拼原始路径端口是否匹配非 443 端口已单独配置URL 带端口但域名列表没带端口配置后是否等了生效时间5 到 10 分钟后再测试改完立刻测试误以为没生效这个清单看起来很简单但我接手过的项目里几乎每一次 downloadFile 相关事故都能在清单里找到对应的行。回到标题本身下载 wx.downloadFile 合法域名 去掉 filepath这件事90% 的场景就是后台配置时把路径写进去了。你只要把域名列表里的路径段去掉、参数问题处理好、端口对得上、配置后等几分钟下载功能基本就顺了。剩下那 10% 的疑难杂症基本都能靠本文第四部分的排查链路解决。按这套经验处理完你大概率不会再被这个问题烦第二次。 
长河君 · 2026/10/15 12:52:23 · 阅读 1.2k 微信小程序wx.downloadFile合法域名配置：去掉filepath后下载就正常了
最近在小程序开发群里看到好几个类似的问题都是被wx.downloadFile的合法域名配置搞到头大。其中下载图片/文件一直 fail报 url not in domain list或者是后台配置域名时填了带路径的地址结果死活不生效更常见的是一堆人问filepath 到底要不要写进域名里。说白了这类问题的根源基本都指向一件事微信小程序的 downloadFile 合法域名根本不允许带路径而且业务代码里出现的filePath、URL 参数里的filepath、域名里的路径这三样东西太容易被混为一谈。这篇文章我就围绕这个标题把我处理过的同类问题完整拆一遍从配置规则、报错解读、调用链路排查到最常见的去掉 filepath 后一切正常的实战场景一次讲透。1. 微信后台域名配置规则为什么带路径必翻车1.1 合法域名到底校验的是什么微信小程序所有网络相关接口在非调试环境下都会做域名合法性校验。wx.downloadFile对应的是后台开发管理-开发设置-服务器域名里的downloadFile 合法域名。这里的校验逻辑非常直白它只校验https://协议 域名含端口这一层路径部分会被忽略或者说带了路径就是不符合格式要求。很多人搞不明白这一点是因为在浏览器里访问一个完整 URL 习惯了比如https://example.com/files/report.pdf觉得填域名的时候也应该把/files/report.pdf一起填进去。实际上后台配置域名时正确的格式只能是https://example.com如果你填成https://example.com/files这个配置在小程序后台大概率会提示域名格式不正确即便侥幸保存成功wx.downloadFile在真机上依然会报url not in domain list。原因很简单微信后台的域名格式校验要求不能包含路径它会校验https://后面的部分必须以域名或 IP 加可选端口结尾不允许出现/之后的路径字符。1.2 一个典型案例填了完整文件地址后下载必失败打个比方某公司给客户做一个内部资料下载的小程序后端返回的文件地址是https://api.somecompany.cn/download/2024/12/123456.pdf。负责配置的同学想省事直接在 downloadFile 合法域名里填了https://api.somecompany.cn/download觉得这样总该匹配到了吧。结果真机一测wx.downloadFile直接 fail报错信息就是经典的downloadFile:fail url not in domain list这个情况的坑点在于开发者工具里如果勾选了不校验合法域名本地调试完全正常一旦手机上打开就是报错。后台配置的域名虽然能保存成功某些情况下微信后台对带路径的格式并不做严格拒绝但校验时不认但实际校验时依然按域名为主路径根本不在匹配范围内于是请求被拦截。1.3 正确的配置姿势正确的做法是在 downloadFile 合法域名里填https://api.somecompany.cn后面的/download/2024/12/123456.pdf不需要管也不用填请求发出时微信只拿https://api.somecompany.cn去比对域名列表。只要域名匹配、备案有效、HTTPS 证书没问题文件下载就不会因为域名问题被拦。这里要额外提一个容易踩的坑如果你用了对象存储的自定义域名比如 CDN 域名是https://cdn.somecompany.cn但接口返回的文件 URL 是https://api.somecompany.cn/download/...这种由后端转发的方式那么 downloadFile 合法域名只需要配置https://api.somecompany.cn。如果文件直链是https://cdn.somecompany.cn/xxx/yyy.pdf那就要把https://cdn.somecompany.cn也加进合法域名列表。这条规则特别容易和 request 合法域名搞混很多人把域名都配在 request 里到了 downloadFile 时报错才想起来还有一个单独的域名列表。2. wx.downloadFile 的三层域名校验关卡2.1 第一关开发者工具里的不校验开关微信开发者工具默认不会拦截未配置的域名因为本地调试阶段你不可能每次都去后台改域名。详情面板 - 本地设置 - 勾选不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书勾上之后任何域名都能请求wx.downloadFile在模拟器和真机调试模式下基本畅通无阻。但注意真机调试和真机预览是两个概念。真机调试有调试模式加持域名校验会被绕过真机预览有时候也会弹出一个开启调试的按钮点开之后同样能绕过校验。这也是为什么很多开发者在预览阶段觉得没问题了结果正式版一上线全挂。2.2 第二关体验版与正式版的硬校验体验版和正式版没有任何开关可以绕过域名校验才会老老实实走后台配置的 downloadFile 合法域名。在这个阶段所有 URL 都会拿去比对一旦不匹配就 fail。我接手过一个模拟项目体验版下载 PDF 一直失败原因就是合法域名只配了https://a.somecompany.cn但代码里实际请求的是https://b.somecompany.cn/download/...。这个可以从报错日志里看得很清楚域名都不在一个列表里自然被拦截。2.3 第三关证书与备案的隐性拦路虎除了域名列表匹配微信还会校验 HTTPS 证书是否有效、域名是否 ICP 备案。这个问题通常是历史遗留的公司用了某个很久没续费的域名证书过期或者域名备案掉了。这时报错可能是:downloadFile:fail 无法连接到服务器或者干脆是网络层失败看起来跟域名配置无关实际是通信层被卡住。排查的时候如果域名已经配了、格式也对就要怀疑证书和备案这两个隐性条件。我给一个非常实用的自检顺序域名列表里有没有这个域名域名后面有没有不小心带了路径这个域名能不能在浏览器里直接打开并触发下载证书链是否完整用浏览器访问一下看地址栏的小锁域名备案有没有掉通常访问时会提示该网站无法访问或未备案只要这五步都过了wx.downloadFile的域名相关问题基本就排干净了。3. 被反复误会的 filepath三种含义必须分清3.1 地址参数里的 filepath很多业务系统的文件接口长这样https://api.somecompany.cn/getFile?filepath/uploads/report_2024_12.pdf这里的filepath是一个业务参数名由后端定义用来告诉服务器想拿哪个文件。它跟微信小程序的合法域名没有任何直接关系。域名校验时只关心https://api.somecompany.cn是否在列表里参数部分完全不影响匹配。但这个场景下容易出现一个隐蔽问题如果你的下载地址是后端动态拼接的而filepath参数里又带了某些特殊字符比如中文、空格、#后端返回的 URL 没有做encodeURIComponent那么wx.downloadFile请求时有可能因为 URL 格式问题导致下载失败。这类问题处理方式很简单前端在拿到 URL 后对参数部分做一次编码const baseUrl https://api.somecompany.cn/getFile; const filepath /uploads/report 2024_12.pdf; const fullUrl ${baseUrl}?filepath${encodeURIComponent(filepath)}; wx.downloadFile({ url: fullUrl, success(res) { // ... } });需要注意的是wx.downloadFile的 URL 本身会被微信做一次合法性校验但它不会替你编码参数所以参数里如果有空格或其他特殊字符最好自己先编码好。否则在某些机型上会表现成時好時坏有时候能下载有时候 fail。3.2 域名配置里的路径段真正要去掉的 filepath回到标题去掉 filepath最核心的含义在配置 downloadFile 合法域名时不能把文件路径或接口路径写进去。举个例子你有一个文件服务的完整地址是https://file.somecompany.cn/path/to/file.pdf在做后台配置时只需要https://file.somecompany.cn/path/to/file.pdf这一段必须去掉。同样如果接口地址是https://api.somecompany.cn/download/file配置域名时也是https://api.somecompany.cn后面那个/download/file不写。如果已经配错了比如后台填了https://file.somecompany.cn/path那么即使前端代码里的 URL 是完整的https://file.somecompany.cn/path/to/file.pdf微信依然会判定域名不匹配。因为校验逻辑拿的是https://file.somecompany.cn和配置里的https://file.somecompany.cn/path比两者不相等直接 fail。我在实际处理中见过最迷惑的操作是把 URL 里的filepath参数名改动去掉比如有人把https://file.somecompany.cn/download?filepath/a.pdf改成了https://file.somecompany.cn/download?url/a.pdf然后以为问题解决了。实际上域名校验从来没管过参数名这样改没有任何意义真正要改的是后台配置里不能出现路径段。3.3 下载保存路径 filePath这是结果不是原因wx.downloadFile成功回调里会返回一个tempFilePath这是临时文件路径。如果你需要把文件保存到本地通常会配合wx.saveFile或wx.openDocument使用这时才会涉及一个叫filePath的概念。但很多人会陷入一个误区以为下载失败是因为没有传filePath然后去wx.downloadFile的url里手动加了一个filepath参数想指定文件路径。这完全不对。wx.downloadFile只需要一个url其他都是可选配置。加不加filepath参数、参数叫什么跟能不能下载成功没有关系唯一的域名校验只认 URL 的协议、域名和端口。wx.downloadFile({ url: https://api.somecompany.cn/download/123456.pdf, success(res) { if (res.statusCode 200) { // res.tempFilePath 就是临时路径不是通过参数传进去的 console.log(res.tempFilePath); } } });这个tempFilePath是系统帮你生成的不是你在调用前传入的。所以如果有人跟你讨论去掉 filepath你要先搞清楚他说的到底是哪一个filepath否则很容易南辕北辙。4. 一次真实的下载失败排查从报错到修复的完整链路4.1 报错信息现场还原模拟项目里出现过这样一次事故。同事在小程序里接了一个下载合同文件的功能本地开发者工具一切正常体验版一测就挂。把报错信息抓出来是downloadFile:fail url not in domain list看一眼后端返回的下载地址https://api.somecompany.cn/contract/download?filepath/contracts/2024/11/abc.pdf再打开小程序后台的 downloadFile 合法域名里面配的是这些https://api.somecompany.cn/contract/download https://api.somecompany.cn这里最大的问题不是域名有没有配而是配了一个带路径的地址。微信后台保存这个配置时大概率会提示格式问题即便保存成功校验逻辑也不认。看到这个配置基本可以断定https://api.somecompany.cn/contract/download这个条目是多余的甚至可能因为格式非法导致整个列表的校验异常。4.2 逐步排查链路遇到url not in domain list我的排查链路是这样的第一步看代码里wx.downloadFile的url到底是什么。把 url 打出来确认协议、域名、端口、路径段。第二步看后台域名列表是否包含这个域名。只看域名部分把https://和后面的/path拆开。比如上面这个例子只需要确认https://api.somecompany.cn在列表里即可。第三步检查后台配置里有没有多余的带路径条目。如果发现https://api.somecompany.cn/contract/download这种立刻删掉重新填https://api.somecompany.cn。删掉之后等几分钟让配置生效。第四步验证 URL 参数是否影响匹配。把?filepath/contracts/2024/11/abc.pdf从 URL 里拆出来或者在前端用一个固定的无参数地址https://api.somecompany.cn/contract/download测试看是否还报同样的错。如果无参数地址能通说明就是域名配置的问题。第五步换真机验证。很多人容易在开发者工具里自我欺骗一定要用体验版二维码在真机上测最好是在 iOS 和 Android 各测一遍因为某些老旧的安卓 WebView 对 URL 编码的容忍度不同可能会额外暴露参数编码问题。4.3 修复操作与验证结果这个案例的修复动作其实很简单登录小程序后台进入 downloadFile 合法域名列表。把https://api.somecompany.cn/contract/download删掉。确认https://api.somecompany.cn在列表里。保存后等待几分钟。重新编译体验版真机测试下载。修复后代码不用动wx.downloadFile的地址依然是https://api.somecompany.cn/contract/download?filepath/contracts/2024/11/abc.pdf下载恢复正常。因为域名校验只匹配协议、域名和端口路径和参数不影响。类似的坑还有另一种变体域名填对了但wx.downloadFile的 url 带了端口比如https://api.somecompany.cn:8443/...而域名列表里只配了https://api.somecompany.cn没有端口。微信的规则是如果 URL 里带了非默认端口域名列表里也需要配置对应的端口。默认情况下 HTTPS 端口是 443可以不用写但如果是 8443 这种就必须在后台配置https://api.somecompany.cn:8443否则照样not in domain list。这两种情况并列在一起基本上覆盖了 downloadFile 域名配置里最常见的两个拦路虎路径和端口。5. 从去掉 filepath延伸出来的项目级建议5.1 统一接口规范让 URL 里的路径和参数名不再制造混乱标题里的去掉 filepath往深处走其实是一个接口规范问题。很多项目下载文件的 URL 是后端直接拼的参数名一会儿叫filepath一会儿叫fileName一会儿又是path。这种随意性会导致排查成本居高不下。我的建议是小程序项目里所有下载类接口统一走一个下载网关https://api.somecompany.cn/download?fileIdxxxxx后端根据fileId找到真实存储路径再决定是走转发还是重定向到对象存储。前端永远只拿fileId不感知文件物理路径。这样做有几个好处域名列表只需要配置https://api.somecompany.cn一个域名文件存储后端可以随意迁移换 CDN、换存储桶小程序端不用改前端不会因为filepath参数里出现#、空格、中文等特殊字符而踩 URL 编码的坑权限校验可以放在下载网关层比直接暴露文件地址安全得多如果你们项目已经是完整文件地址 路径参数的模式强制要求后端返回的 URL 必须做过encodeURIComponent并且路径参数名统一最好在接口文档里约定为fileId或fileKey不要再叫filepath从命名上减少误解。5.2 前端调用层的防御式写法即使理论上域名配置对了前端也应该写一段防御式逻辑避免用户在弱网或异常情况下被下载失败四个字劝退。function downloadFile(url) { return new Promise((resolve, reject) { wx.downloadFile({ url, timeout: 30000, success(res) { if (res.statusCode 200) { resolve(res.tempFilePath); } else { reject(new Error(下载失败HTTP 状态码${res.statusCode})); } }, fail(err) { // 把 err.errMsg 打出来辅助定位 console.error(downloadFile fail, err.errMsg); reject(err); } }); }); }timeout参数很关键不设的话某些低端机会长时间卡住用户会以为小程序死了。实测下来 iOS 上 30 秒是一个比较稳的阈值再长对用户来说就没耐心了。下载成功后的临时文件如果需要长期保存尽早调用wx.saveFile因为临时文件在小程序退出后可能被清理。wx.saveFile的filePath参数是可选的不传就自动生成所以不要纠结于要不要去掉 filepath这类问题保存逻辑本来就跟你传不传无关。5.3 一个容易漏掉的细节域名配置生效时间微信后台的域名配置保存后并不是秒级生效。我以前也踩过这个坑保存完立刻去真机测还是报url not in domain list就以为配置方法不对反反复复试了十几次。后来才知道域名配置有几分钟到十几分钟的缓存时间。所以在你修改完 downloadFile 合法域名之后不要马上测试等 5 到 10 分钟再试。如果修改完还是报原来的错优先排查是不是缓存没刷而不是马上怀疑配置格式。另外downloadFile和request的合法域名是独立的两个列表改了downloadFile不会影响request反之亦然。有时候你发现wx.request能通但wx.downloadFile不行往往就是因为只配了 request 域名忘了配 downloadFile 域名。这两个列表虽然字段长得一样但互不相通必须分别配置。5.4 下载文件保存后的打开姿势如果是下载 PDF、Word 之类的文档保存完成后要打开用wx.openDocument。这里也有一个常见误区有些人以为wx.openDocument也需要配置域名其实不用它读取的是本地文件路径完全不涉及网络请求。真正需要域名配置的只有下载那一步。wx.saveFile({ tempFilePath: res.tempFilePath, success(saveRes) { wx.openDocument({ filePath: saveRes.savedFilePath, fileType: pdf, showMenu: true, success() { // 打开成功 } }); } });showMenu这个参数我建议设成true这样用户打开文件后右上角能弹出菜单可以转发、收藏、保存到通讯录之类的。如果不设置很多机型上的文档页面只是一个纯阅读页没法做后续操作体验上会差不少。5.5 项目上线前的域名自查清单我的习惯是在每次发布正式版之前把域名相关的几项全部过一遍。查完这几项downloadFile 域名问题基本不会带病上线检查项预期结果常见错误downloadFile 合法域名是否已配置包含所有实际使用的下载域名只配了 request 域名域名是否带路径不带只有协议 域名 可选端口填了/download等路径HTTPS 证书有效性浏览器访问正常无安全警告证书过期或链不完整域名是否 ICP 备案备案在有效期内备案掉了或新域名未备案URL 参数是否已编码无中文、空格、#等裸参数后端直接拼原始路径端口是否匹配非 443 端口已单独配置URL 带端口但域名列表没带端口配置后是否等了生效时间5 到 10 分钟后再测试改完立刻测试误以为没生效这个清单看起来很简单但我接手过的项目里几乎每一次 downloadFile 相关事故都能在清单里找到对应的行。回到标题本身下载 wx.downloadFile 合法域名 去掉 filepath这件事90% 的场景就是后台配置时把路径写进去了。你只要把域名列表里的路径段去掉、参数问题处理好、端口对得上、配置后等几分钟下载功能基本就顺了。剩下那 10% 的疑难杂症基本都能靠本文第四部分的排查链路解决。按这套经验处理完你大概率不会再被这个问题烦第二次。