企业官网建设流程全解析

1. 从一次真机白屏说起：这个问题的典型现场

第一次碰到这个情况，是在一个已经跑了大半年的跨端项目上。开发阶段一切正常，本地调试、真机预览、体验版扫码，数据都能正常拉取，页面渲染也没毛病。等到正式提审、发布上线之后，用户反馈打开小程序是一片空白，列表页转圈转到天荒地老，控制台里安安静静，连个像样的报错都没有。这种"开发环境好好的、线上就是拿不到数据"的现象，是跨端开发里最让人头疼的一类问题，因为它往往不是代码逻辑写错了，而是运行环境、域名配置、构建产物这三者之间某个环节对不上。

标题里提到的场景很具体：用 uni-app 做跨端开发，后端或云服务用的是支付宝云（也就是阿里系的云服务能力，比如云函数、云数据库、云存储这类 Serverless 形态的服务），最终产物要发布成微信小程序。这三者凑在一起，天然就存在一层"跨生态"的缝隙——支付宝云的服务体系是为阿里生态设计的，微信小程序则有自己的域名白名单、请求限制和运行沙箱。数据拿不到，绝大多数时候就卡在这条缝隙上。

这篇内容适合两类人看：一类是正在用 uni-app 做多端发布、后端接了云服务的开发者，另一类是已经上线但被"线上无数据"问题卡住的同学。我会把这类问题的排查链路完整走一遍，从最表层的现象一路挖到构建配置和云服务侧的细节，中间穿插我自己踩过的坑和几个容易被忽略的检查点。你不需要有很深的云端背景，跟着思路走就能定位到问题所在。

先说结论方向，免得你看到一半才反应过来："获取不到数据"在小程序线上环境里，九成以上不是接口挂了，而是请求根本没发出去，或者发出去了被拦在了域名校验、协议、跨域、环境变量这几道关卡上。下面我们一层层拆。

2. 先分清"没数据"的三种形态，别一上来就改代码

很多人一遇到线上没数据，第一反应是去翻接口代码、加日志、怀疑后端。这个顺序其实是反的。正确的做法是先判断"没数据"到底属于哪一种形态，因为不同形态对应的排查路径完全不同。我一般把它分成三类，你可以对照自己的现象快速归类。

2.1 形态一：请求压根没发出去

表现是网络面板里干干净净，没有任何请求记录，或者只有静态资源请求。这种情况基本可以断定是代码在发请求之前就中断了，常见原因包括：运行环境判断逻辑把小程序端的分支走错了、某个全局变量在线上是 undefined 导致提前 return、或者请求封装里的 baseURL 在小程序环境下拼成了空字符串。

我遇到过一次特别典型的：请求封装里用了一个环境判断，本地走的是process.env.NODE_ENV === 'development'分支拿测试地址，线上走生产地址。结果构建的时候环境变量没注入进去，线上分支拿到的 baseURL 是 undefined，拼接出来的 URL 是undefined/api/list，请求发出去直接被判定为非法地址，连网络面板都不显示。这种问题的隐蔽性在于，代码逻辑本身没错，错在构建环节。

2.2 形态二：请求发出去了，但被拦截

网络面板里能看到请求，但状态是失败、被取消，或者返回了一个跟业务无关的错误页。这类情况最常见的就是域名不在微信小程序的白名单里。微信小程序对网络请求有严格限制，所有 request、uploadFile、downloadFile 的域名都必须提前在后台配置，而且必须是 HTTPS，不能用 IP，不能带端口（非标准端口会被拒）。如果你用的是支付宝云提供的默认域名，很可能这个域名压根没加进微信的白名单，请求自然被拦。

还有一种拦截是协议层面的。支付宝云的部分服务默认可能走的是 HTTP 或者某些特殊协议，而微信小程序强制要求 HTTPS。这种"协议不匹配"在开发工具里有时会被宽松处理，但真机和线上环境是严格执行的，所以会出现"工具里能跑、真机不行"的割裂现象。

2.3 形态三：请求成功返回，但数据是空的

这种最迷惑人，因为网络面板显示 200，看起来一切正常，但页面就是不渲染。原因通常有三类：返回结构跟前端解析逻辑对不上（比如云端包了一层data.data，前端只取了data）、云端返回的是错误码但 HTTP 状态是 200、或者数据本身在云端就是空的（比如云数据库的权限规则把线上环境的读取拦掉了）。

把这三类分清楚之后，排查就有了方向。下面这张表可以帮你快速定位：

3. 域名白名单这道坎：为什么本地能通、线上不通

这是标题场景里最高频的坑，值得单独拎出来讲透。很多人对"域名白名单"的理解停留在"加一下就行"，但实际上它有几个容易踩的细节，尤其是当你用的是云服务提供的默认域名时。

3.1 白名单的配置位置和生效逻辑

微信小程序的请求域名配置在后台的"开发管理 - 开发设置 - 服务器域名"里，分四个类别：request 合法域名、socket 合法域名、uploadFile 合法域名、downloadFile 合法域名。你要根据实际用到的能力分别配置，只配了 request 但代码里用了 uploadFile，上传照样失败。

关键点在于生效时机。这个配置修改后，开发工具里可能需要重新编译甚至重启才生效，真机则需要重新打开小程序。更坑的是，体验版和正式版读取的是同一份配置，但如果你在开发阶段用的是"不校验合法域名"的调试开关，那本地一切正常，一旦关掉这个开关或者发布上线，问题立刻暴露。所以我的习惯是：开发阶段就把域名配好，全程开着校验调试，别依赖那个"跳过校验"的开关，否则等于把问题推迟到上线才爆发。

3.2 云服务默认域名的三个陷阱

用支付宝云这类云服务时，平台通常会给你分配一个默认的服务域名。这个域名直接拿来用，往往会撞上三个陷阱：

第一个是域名归属问题。云服务分配的默认域名，其备案主体和微信小程序的备案主体可能不一致。微信对这一点查得比较严，虽然不一定会直接拒绝，但在某些审核场景下会要求域名主体与小程序主体相关。稳妥的做法是绑定自己的域名，做好备案和 HTTPS 证书。

第二个是域名稳定性。默认域名有时是共享的、带随机后缀的，或者平台会调整。一旦域名变了，白名单里的配置就失效了，线上立刻断数据。这种"某天突然没数据"的情况，八成是云端域名悄悄变了。

第三个是端口和路径。白名单只认域名，不认端口。如果你的云服务地址带了非 443 端口，配进去也没用。路径部分倒是不影响白名单校验，但会影响实际请求，这个后面讲。

3.3 一个自查清单

在怀疑代码之前，先按这个清单过一遍，能省掉大量无效排查：

• 打开微信开发者工具，关掉"不校验合法域名"开关，重新编译，看请求是否还通。
• 在小程序后台确认 request 域名列表里有你实际请求的域名，注意是完全匹配，子域名不算。
• 确认域名是 HTTPS，证书有效且未过期。
• 确认域名没有使用非标准端口。
• 如果是云服务默认域名，确认它近期没有变更。

提示：真机调试时，可以在手机端打开调试模式，用 vConsole 看网络请求，比在电脑上猜要快得多。很多"线上没数据"的问题，在真机 vConsole 里一眼就能看到是被域名校验拦了。

4. 构建与环境变量：线上和本地跑的不是同一套配置

域名配好了，请求还是发不出去，那就要往构建环节查。uni-app 的跨端构建有个特点：同一份代码，编译到不同平台时，条件编译和环境变量的处理方式不一样。这就导致"本地跑的是 A 配置，线上跑的是 B 配置"，而 B 配置可能是错的。

4.1 条件编译把小程序端的分支写错了

uni-app 用#ifdef/#ifndef做条件编译，语法上很容易写错平台标识。比如你想让微信小程序走某个分支，写成了#ifdef MP-WEIXIN是对的，但如果手滑写成#ifdef MP-WEIXIN（带空格）或者大小写不对，这个分支就不会生效，代码会走到默认分支或者干脆被剔除。这种错误在编辑器里不会有任何提示，编译也不报错，但运行时的行为完全不对。

我的建议是，把所有跟平台相关的请求配置集中到一个文件里，用清晰的条件编译块管理，并且在每个分支里加一行启动日志（比如打印当前 baseURL），线上出问题时看日志就能确认走的是哪个分支。日志在正式环境可以关掉，但排查阶段非常有用。

4.2 环境变量在构建时被"固化"

前端项目里的环境变量，本质上是在构建时被替换成字面量的，不是运行时读取的。这意味着你在.env.production里配的值，必须在构建命令执行时就被正确加载。如果构建脚本没有指定 mode，或者 CI 环境里缺少对应的 env 文件，构建出来的产物里环境变量就是空的。

我见过一个案例：本地npm run build一切正常，因为本地有.env.production文件；但 CI 流水线里只 checkout 了代码，env 文件被 gitignore 掉了，构建出来的包里 baseURL 是空字符串。线上请求全部发到了当前页面域名下，自然拿不到数据。解决办法要么是把必要的 env 配置通过 CI 的变量注入，要么是在构建脚本里显式指定，别依赖本地文件。

4.3 云服务 SDK 的初始化时机

如果数据是通过云服务 SDK 拉取的（而不是普通 HTTP 请求），还要注意 SDK 的初始化。云服务 SDK 通常需要在应用启动时用一组密钥或配置初始化，这个初始化如果放在了某个页面生命周期里，而线上首屏加载顺序跟本地不同，就可能出现"SDK 还没初始化完，请求已经发出去了"的竞态问题。表现就是偶发性的拿不到数据，刷新一下又好了。

稳妥的做法是把 SDK 初始化提到应用入口（比如App.vue的onLaunch），并且用一个 Promise 或者状态标记保证后续请求在初始化完成后再发。这个细节在文档里往往一笔带过，但线上偶发问题里它出现的频率不低。

5. 云端那一侧：权限规则和返回结构才是隐形杀手

前面讲的都是"请求出不去"的问题，这一节讲"请求出去了但拿不到想要的数据"。这类问题的排查难度更高，因为网络层面看起来一切正常，问题藏在云端的配置和数据结构里。

5.1 云数据库的权限规则按环境区分

很多云服务（包括支付宝云提供的数据库能力）都有权限规则的概念，用来控制哪些客户端能读哪些数据。这些规则经常是分环境的：开发环境为了调试方便，规则放得很松；生产环境为了安全，规则收得很紧。如果你在开发环境测试时数据正常，上线后读不到，很可能就是生产环境的权限规则把当前请求拦掉了。

排查方法很直接：去云服务控制台，找到对应数据库的权限配置，确认线上环境的读规则是否允许当前客户端的身份读取目标集合。有些规则是基于用户身份的，如果小程序端的登录态在线上没有正确建立，请求就是匿名的，匿名身份自然读不到受保护的数据。这时候表面现象是"返回空数组"或者"权限不足"，但 HTTP 状态可能是 200，非常具有迷惑性。

5.2 返回结构的多层嵌套

云服务的接口返回结构往往比普通 REST 接口多包几层。比如普通接口返回{ code: 0, data: [...] }，云函数可能返回{ success: true, result: { data: [...] } }，再套一层云服务自己的封装，就变成了{ requestId: 'xxx', data: { success: true, result: { data: [...] } } }。前端如果按老结构解析，取到的就是 undefined，页面自然空白。

这种问题的排查技巧是：在请求封装里统一打印一次原始响应，别在业务代码里猜结构。我一般会在封装的响应拦截器里加一行console.log('raw response', res)，线上排查时打开调试看这一行，结构一目了然。确认结构后再调整解析逻辑，比盲目改业务代码高效得多。

5.3 分页和查询条件的默认值差异

还有一个容易被忽略的点：云数据库的查询在某些环境下有默认条数限制，或者默认的排序、过滤条件跟开发环境不一致。比如开发环境数据少，不传分页参数也能全查出来；线上数据多了，不传分页就只返回前若干条，甚至返回空。这类问题不是"拿不到数据"，而是"拿到的数据不符合预期"，但用户感知上就是"没数据"。

处理办法是在查询时显式指定分页参数、排序字段和过滤条件，不要依赖默认值。云端能力的默认行为在不同版本、不同环境下可能有差异，显式声明是最稳的。

6. 一套可复现的排查链路：从现象到根因

讲完原理，给一套我自己常用的排查流程。这套流程的价值在于顺序——从成本最低、最可能命中的检查开始，逐步深入，避免一上来就大动干戈。

6.1 第一步：真机 + 关闭校验 + 看网络

拿到一台真机，打开小程序，进入调试模式（vConsole），关掉开发工具的域名校验开关，然后操作到出问题的页面。看 vConsole 的网络面板：

• 没有请求：跳到第 6.2 步查构建和环境变量。
• 请求失败/被拦：跳到第 6.3 步查域名和协议。
• 请求成功但数据空：跳到第 6.4 步查云端和解析。

这一步能在五分钟内把问题归类，是整个排查的锚点。

6.2 第二步：确认线上产物里的配置值

如果请求没发出去，最可能是配置问题。在代码里临时加一行日志，打印请求封装用到的 baseURL、环境标识、SDK 初始化状态，然后重新构建发布一个测试版本，看真机日志里的值对不对。重点看三个：baseURL 是不是空或 undefined、环境标识是不是指向了错误的分支、SDK 是否已初始化完成。

这一步的关键是看构建产物里的真实值，而不是看源码里的值。源码里写的是变量，产物里是替换后的字面量，两者可能不一致。

6.3 第三步：逐项核对域名白名单

如果请求被拦，去小程序后台逐项核对。注意几个细节：域名要完全匹配、要 HTTPS、不能带端口、四个类别按需配置。如果用的是云服务默认域名，去云服务控制台确认这个域名当前是否有效、是否近期变更过。有条件的话，绑定自有域名并做好备案和证书，一劳永逸。

核对完之后，重新编译、重新打开小程序，再测一次。域名配置的生效有时需要一点时间，别改完立刻下结论。

6.4 第四步：打印原始响应，核对云端规则

如果请求成功但数据空，先在响应拦截器里打印原始响应，确认结构。结构对了还空，就去云服务控制台查权限规则和查询条件。重点确认：线上环境的读权限是否放开给当前身份、登录态是否在请求前已建立、查询是否带了必要的分页和过滤参数。

这一步最容易陷入"改前端代码"的误区。实际上如果云端规则拦了，前端怎么改都没用，必须先确认云端放行。

7. 几个我踩过、但文档里不会写的细节

最后分享几个实战中总结的细节，都是那种"知道了能省半天、不知道能卡一周"的经验。

第一个是体验版和正式版的差异。很多人用体验版测试通过就以为万事大吉，但体验版和正式版在某些配置上读取的时机不同，尤其是域名白名单和云服务环境。我的习惯是，正式发布前一定用一个独立的测试小程序（或者灰度环境）走一遍完整流程，别拿体验版当最终验证。

第二个是缓存导致的假象。小程序有本地缓存机制，有时候你改了配置、重新发布了，但用户端还是旧版本的行为，因为缓存没清。排查时记得在真机上清一次缓存，或者用"删除小程序重新进入"的方式排除缓存干扰。我遇到过改完域名配置后仍然不通，折腾半天发现是缓存了旧的请求失败结果。

第三个是云服务侧的日志比前端日志更可信。前端看到的"请求失败"可能有很多层原因，但云服务控制台的调用日志能直接告诉你请求有没有到达、到达后是被哪条规则拦的、返回了什么。排查云端问题时，优先看云服务侧的日志，比在前端加一堆 console 高效得多。

第四个是别忽视网络环境。有些企业内网或者特定运营商的网络会对某些域名有额外限制，导致部分用户能拿到数据、部分用户不能。这种"部分用户反馈"的问题，排查时要多找几个不同网络环境的设备测试，别只在自己工位上复现。

注意：所有涉及域名、证书、备案的操作，都要提前规划，别等到发布前夜才发现域名没备案。这类流程性的事情，卡起人来比技术问题还难受。

这套排查思路的核心其实就一句话：先归类现象，再按成本从低到高逐层验证，每一步都用真机和真实产物说话，别在本地环境里自嗨。跨端加云服务的组合，问题往往不在某一端，而在两端交接的那条缝上，盯住那条缝，大部分"获取不到数据"都能定位到根因。