微信小程序本地开发，这些坑你踩过吗？

打开微信开发者工具，点下编译，页面空白。控制台报错，某个请求失败。你第一反应是后端接口挂了，跑去问同事，人家说线上好好的。这时候你才开始意识到，问题出在本地。微信小程序的本地开发，跟普通网页开发看着像，骨子里完全是两回事。今天不聊那些官方文档里写了八百遍的入门教程，专门说说那些坑，那些你踩过之后才恍然大悟的坑。

第一个坑，八成人都栽在“域名校验”上。本地调试的时候，你想请求自己电脑上起的服务，比如`http://localhost:8080`，结果微信开发者工具直接给你拦下来，告诉你“不在以下request合法域名列表中”。这时候你可能想，我勾选“不校验合法域名”不就行了？确实，开发工具右上角有个“详情”按钮，里面有个“本地设置”，勾上“不校验合法域名、web-view（业务域名）、TLS版本以及HTTPS证书”。但问题来了，这个设置只对当前项目生效，而且换台电脑、换个项目，你都得重新勾。更坑的是，真机预览的时候，这个勾选完全没用，你手机上打开小程序，照样请求失败。所以正确做法是，本地起服务的时候，直接用`http://127.0.0.1`配上端口，同时在开发工具的“本地设置”里勾掉校验，这样至少开发阶段能跑通。

第二个坑，跟“缓存”有关。你改了代码，重新编译，页面还是老样子。你以为是工具没刷新，点了好几次编译，还是没用。后来发现，是小程序里的`wx.setStorageSync`把旧数据存进去了，每次启动都优先读缓存。这问题在本地开发时特别隐蔽，因为你不容易注意到自己什么时候写了缓存逻辑。解决思路很简单：开发阶段，在`App.onLaunch`里加一行`wx.clearStorageSync()`，或者干脆在工具里清缓存。但如果你忘了，调试的时候数据不对，你可能会怀疑是自己的逻辑写错了，花半天时间排查，最后发现是缓存捣的鬼。

第三个坑，是“本地路径”和“真实路径”的混淆。你在代码里写了图片路径`/images/logo.png`，本地跑得好好的，一上传体验版，图片全挂了。为什么？因为你用的是相对路径，而小程序打包之后，资源路径会被重新处理。更麻烦的是，如果你在本地开发时用了`wx.getFileSystemManager().readFile`去读一个绝对路径，比如`/Users/yourname/project/images/logo.png`，在真机上这个路径根本不存在。所以本地开发时，凡是涉及文件读取、路径拼接的，一定要用`wx.env.USER_DATA_PATH`或者相对路径，千万别写死。这个坑一旦踩了，排查起来特别痛苦，因为你本地一切正常，只有真机有毛病，你只能一遍遍预览调试。

第四个坑，关于“URL参数”的编码问题。你本地开发时，接口地址可能带中文参数，或者带特殊字符，比如`http://localhost:8080/api?name=张三`。开发工具可能自动帮你编码了，你也没注意。但真机上，部分机型或者特定网络环境下，中文参数没编码就直接请求，后端解析出来是乱码，或者直接报400错误。这个坑的隐蔽性在于，你本地测试没问题，模拟器也没问题，但用户手机上就出问题。解决办法很简单：所有请求参数，统一用`encodeURIComponent`处理一遍。别嫌麻烦，这能省掉你后面一大堆投诉。

第五个坑，是“网络请求超时”的设置。小程序的`wx.request`默认超时时间是60秒，但本地开发时，你电脑上起的服务可能响应慢，或者你断点调试的时候卡住了，请求一直挂在那儿。你以为是小程序卡了，其实是超时时间太长。反过来，如果你把超时时间设得太短，比如3秒，本地调试时稍微慢一点就报“request:fail timeout”，你会误以为是网络问题。建议本地开发时，把超时时间设成10秒，同时在后端接口加个日志，看看到底是哪里慢。别把时间浪费在猜测上。

第六个坑，关于“端口占用”。你本地起了好几个服务，8080被占了，换到8081，结果小程序请求的还是8080。你检查代码，明明写的是8081，但请求就是发不出去。后来发现，是微信开发者工具缓存了DNS解析或者端口映射。这个坑解决起来很简单：重启工具，或者换个端口。但如果你不意识到是端口问题，可能会去检查代码、检查防火墙，绕一大圈。

第七个坑，是“真机调试”和“模拟器”的差异。模拟器上你的布局完美，字体大小合适，滚动流畅。一上真机，字体忽大忽小，布局错位，甚至某些组件直接不显示。这是因为模拟器的渲染引擎和真机的WebView版本有差异，特别是`rpx`单位的换算，不同机型屏幕宽度不同，换算结果也不同。本地开发时，别只用模拟器调试，得经常点“预览”生成二维码，拿手机扫一下。但真机调试有个问题，就是调试模式下的网络请求和正式环境不同，有时候你本地能调通，真机调试也能调通，一上传体验版就出问题。所以，最保险的做法是，每次改完代码，先预览，再上传体验版，拿体验版测一轮。

最后一个坑，是“环境切换”的混乱。你本地开发时，可能同时对接开发环境、测试环境、生产环境的接口。你写了多个配置文件，手动切换。但有时候忘了切，或者切错了，导致本地调试时请求的是生产环境接口，改数据了都不知道。更坑的是，某些接口有权限校验，你本地调试时用的身份信息是测试账号，但环境切错了，结果报权限不足，你以为是代码问题，排查半天。建议用小程序提供的`wx.getAccountInfoSync()`来判断当前环境，或者统一封装一个`request`方法，根据开发工具里的“编译模式”自动切换环境。别手动改，真的容易出错。

说来说去，这些坑的本质就一句话：本地开发环境和真实运行环境，差异比你想象的大得多。你不可能在本地模拟出所有真机的情况，但至少可以提前规避掉大部分常见的坑。别嫌麻烦，每次新建项目，先把域名校验、缓存清理、路径处理、参数编码这些基础配置弄好，能省掉后面无数个加班的夜晚。你踩过几个？评论区聊聊，看看谁是最惨的那个。