企业官网建设流程全解析

简介：微信扫码一键连接WiFi的小程序源码，面向小程序开发者以及需要为咖啡馆、商场等公共场所提供快速联网服务的运营方。整个zip压缩包共16个文件，包含6个json配置文件、5个js逻辑脚本、3个wxss样式表与2个wxml页面结构，体积仅104KB，目录划分清晰。已有1119人学习下载，源码完整呈现了从调用微信扫码API、解析二维码中的SSID与密码，到申请网络权限并调用系统接口完成WiFi连接的全流程。通过阅读项目中的全局逻辑、全局配置、页面与工具模块，可理解小程序生命周期、页面注册、函数封装等要点；同时涉及WXML/WXSS界面搭建、JS交互与网络权限配置，非常适合想系统学习微信小程序开发或快速落地同类功能的读者。这份源码也可作为模板二次开发，调整界面与逻辑后直接应用。

1. 微信扫码一键连接WiFi小程序源码：真能落地的技术方案长什么样

先下个结论：这个标题指向的不是“微信扫一下码就自动连上WiFi”的魔法，而是一条由二维码链接规则、小程序落地页、wx.connectWifi 三个环节拼出来的标准链路。场景很明确——餐馆门口贴个码，客人扫完进小程序点一下就连上WiFi；民宿床头放张卡，访客再也不用问密码。它对门店、共享办公、家庭访客都是体验刚需，也是少有的低成本物联网入口。适合两类人：想给自己或客户做扫码连网体验的小程序开发者，以及想拿源码做商业化交付的从业者。把原理、代码、坑一次讲清，你看完能直接判断这方向值不值得投。

2. 小程序连WiFi的能力边界：关键API、权限链路与二维码限制

2.1 四个API组成的连接链路：startWifi、getWifiList、onGetWifiList、connectWifi

小程序连接WiFi的能力由一组API控制，必须成对使用。wx.startWifi初始化系统WiFi模块；wx.getWifiList发出获取列表请求；wx.onGetWifiList在列表准备完成后触发回调；wx.connectWifi发起实际连接。这条链路里最容易翻车的是对getWifiList的误解——它只负责发起请求，真正的数据是在onGetWifiList这个监听回调里拿到的。

// 初始化WiFi模块并获取列表的标准写法 wx.startWifi({ success() { wx.getWifiList({ success() { // 数据不在这里返回，需要监听 onGetWifiList }, fail(err) { console.error('获取WiFi列表请求失败', err.errMsg) } }) } }) wx.onGetWifiList((res) => { const list = res.wifiList || [] this.setData({ wifiList: list.map(item => ({ ssid: item.SSID, signal: item.signalStrength, // 部分机型不返回BSSID，拿不到时不要用于去重 encrypted: item.encryptType })) }) })

为什么这样设计？官方说法是getWifiList只是一个触发动作，结果通过事件回调推送。实际原因是微信想避免开发者用同步方式高频拉取WiFi数据。注意onGetWifiList通常只触发一次，第二次调用getWifiList时不会重新触发，需要先stopWifi再startWifi重置模块。这个细节在多页面导航时很容易踩中，我一开始就吃过这个亏。

signalStrength单位是dBm，数值越大信号越好，-30左右是满格，-80以下基本不可用。页面显示“信号强/中/弱”时，阈值建议按-50以上为强、-67以上为中、以下为弱来切分。这个经验值比按百分比显示的体验准确得多，-67就是大多数人能感知的流畅分界点。

2.2 connectWifi参数逐个拆开：partialInfo、maunal与错误码的坑

connectWifi是核心API，参数不多但每个都有讲究。SSID必须和路由器配置完全一致，大小写、空格都不能差；password为空时表示连接开放网络；partialInfo决定是否弹系统确认框，true为静默连接，false弹窗提醒；maunal这个参数是官方文档里的历史拼写错误，意思是“是否由系统自动管理连接”，但参数名必须原样抄，写成manual会直接报错。

wx.connectWifi({ SSID: 'CoffeeShop-WiFi', password: 'coffee888', partialInfo: true, maunal: false, success(res) { // 注意：这里的success不代表手机已联网，只代表连接指令被接收 console.log('connect success', res) }, fail(err) { // 常见错误：-13000 定位未授权、-13001 连接失败 console.error('connect fail', err.errMsg) } })

错误码值得记一下。errMsg里出现-13000表示系统无法启动WiFi服务，基本是位置权限没开；-13001多数是密码错误或信号太弱；还有一种安卓特有的情况，路由器拒绝连接请求，提示类似已满或MAC过滤。看到错误码再去查对应环境配置，比埋头改代码效率高得多。partialInfo在iOS上会被系统忽略，强制弹窗确认，这是系统策略，别想着绕过。

2.3 位置权限是不可绕过的前置：授权链路的三种状态处理

位置权限在整个连接流程里扮演守门员。系统把扫描WiFi视为地理信息采集行为，不授权就不给数据。微信的授权链路是：wx.getSetting查询状态，wx.authorize发起弹窗授权，用户拒绝后引导到设置页。写这段代码时必须处理三种状态：已授权、未授权但可弹窗、永久拒绝。

function ensureLocationAuth() { return new Promise((resolve, reject) => { wx.getSetting({ success(res) { if (res.authSetting['scope.userLocation']) { resolve(true) } else if (res.authSetting['scope.userLocation'] === false) { // 用户之前拒绝过，必须引导去设置页 wx.showModal({ title: '需要位置权限', content: '请在设置中开启位置权限，否则无法扫描WiFi', confirmText: '去设置', success(modalRes) { if (modalRes.confirm) { wx.openSetting({ success: (settingRes) => { settingRes.authSetting['scope.userLocation'] ? resolve(true) : reject(new Error('权限未开启')) } }) } } }) } else { wx.authorize({ scope: 'scope.userLocation', success: () => resolve(true), fail: () => reject(new Error('用户拒绝授权')) }) } }, fail: () => reject(new Error('getSetting调用失败')) }) }) }

这段代码的细节在于wx.authorize只能弹一次窗，用户第一次点拒绝后，后续调用不会再弹窗，必须走wx.openSetting让用户到设置页手动开启。很多人只写主逻辑分支，真实用户卡在第二次拒绝后的死循环里，体验就很糟糕。授权时机建议放在用户点击“扫描WiFi”按钮后，别在onLoad里弹，用户还没理解用途就弹窗只会拒绝。

2.4 扫码的两种能力边界：为什么WIFI:T格式的二维码扫了没反应

市面上所有WiFi二维码教程都会提到ZXing的标准格式：WIFI:T:WPA;S:xxx;P:xxx;;。但小程序方案的第一个误区就在这里：直接用微信扫这个格式，只会提示“二维码包含WiFi信息，请使用系统相机或设置”，微信不会自动连接或跳转。它没有原生API去解析这类非URL二维码。真正可行的路径是“扫普通链接二维码打开小程序”能力。

在小程序后台配置一个URL前缀规则，二维码内容做成该前缀下的HTTPS链接。用户扫码后微信直接打开小程序指定页面，WiFi信息放在URL参数里或由后端根据参数查询。二维码承载的不再是WiFi信息而是一个业务链接。配置时要注意域名必须完成ICP备案，且需要在后台完成业务域名校验，校验文件放根目录。规则生效有审核期，快则十几分钟，慢则几小时，线上活动要提前一天准备。

3. 项目骨架与数据设计：从权限配置到二维码生成的准备工作

3.1 新建项目时的关键配置：app.json权限声明与页面注册

创建项目时，先裁掉模板里的示例代码。app.json里需要做三件事：声明pages列表、声明位置权限用途、确认基础库版本。权限描述的desc文案要写清楚用途，直接说“用于扫描附近WiFi并完成连接”，别用“为了更好的体验”这类空话。页面注册顺序也有讲究，首页通常是index，扫码落地页是connect，建议在index的onLoad里判断启动参数并redirectTo到connect页。

{ "pages": [ "pages/index/index", "pages/connect/connect", "pages/admin/admin" ], "window": { "navigationBarTitleText": "WiFi一键连", "navigationBarBackgroundColor": "#ffffff" }, "permission": { "scope.userLocation": { "desc": "用于扫描附近WiFi并完成连接" } } }

实践中建议把project.config.json里的libVersion设成较新的稳定版本，老基础库在connectWifi上有不少机型兼容问题。navigationBarTitleText可以按实际门店品牌改，示例里的“WiFi一键连”只是个占位名。不要用中文作为路径名，开发调试时编码不一致会平白多出一些奇怪问题。

3.2 WiFi信息存储的两种模式与选择建议

WiFi信息存哪里，直接决定方案复杂度。第一种纯前端模式，把WiFi列表写成JSON文件或缓存，适合单点家庭使用，零服务器成本，换密码要发版更新；第二种服务端模式，SSID和密码存在后端数据库，小程序通过接口查询，二维码不暴露真正密码。门店和商业化场景无脑选第二种，换密码改数据库即可，二维码不用重新打印。

// 纯前端模式示例 const wifiDatabase = { storeId: 'store_001', networks: [ { ssid: 'CoffeeShop-WiFi', password: 'coffee888', band: '2.4G/5G' }, { ssid: 'CoffeeShop-Guest', password: 'guest123', band: '2.4G' } ] } // 服务端模式接口返回结构 // GET /api/wifi/detail?store_id=store_001&network_id=net_001 // { // "code": 0, // "data": { // "ssid": "CoffeeShop-WiFi", // "password": "coffee888", // "encrypt": "WPA2", // "expire": 1700000000 // } // }

决策建议就一条：如果WiFi密码一年都不改一次，前端模式够用；换密码是常态，或需要按门店维度管理多个WiFi，直接上服务端。服务端数据模型至少要包含store_id、ssid、password、encrypt_type、band、sort字段。band字段在高密度门店场景辅助连接策略，比如优先推荐5G频段。

3.3 二维码生成的编码规范与长度约束

二维码内容必须是URL格式，且要控制长度。URL太长二维码图案会过密，打印后扫描成功率直线下降。建议URL里只放store_id和network_id两个短参数，不要放明文密码。如果业务上必须离线可用，至少用固定密钥AES加密密码，但密钥管理本身是另一个泄露点，能不做就不做。

// 二维码内容构造 const WIFI_QR_URL = 'https://wifi.example.com/wifi' function buildQrContent(storeId, networkId) { return `${WIFI_QR_URL}?store_id=${storeId}&network_id=${networkId}` } // 生成二维码时控制容错率 // errorCorrectionLevel: 'M' 约15%容错，保障印刷后仍可识别 drawQrcode({ width: 258, height: 258, canvasId: 'qrCanvas', text: buildQrContent('store_001', 'net_001'), errorCorrectionLevel: 'M' })

errorCorrectionLevel是容错等级：L约7%，M约15%，Q约25%，H约30%。打印场景选M或Q都行，M在正常尺寸打印时足够；如果要做成杯垫或卡片且容易被磨损，选Q更保险。二维码打印尺寸建议不小于3cm×3cm，太小了部分手机扫码困难。这里用的是canvas绘制方案，如果你接的是后端生成接口，后端直接返回PNG图片URL即可，小程序端只用image标签展示。

3.4 管理页面：最简单的增删改查与二维码生成入口

管理页面向店长角色，能看到当前所有WiFi列表，支持新增、修改、删除、生成二维码。功能不复杂，但权限控制不能省。开发阶段可以先不做登录，上线前一定要加管理员身份校验，否则任何人扫码进来都能改密码，后果很尴尬。

// 保存WiFi配置的接口调用封装 function saveWifiConfig(wifiData) { return new Promise((resolve, reject) => { wx.request({ url: 'https://api.example.com/wifi/save', method: 'POST', data: { id: wifiData.id, ssid: wifiData.ssid, password: wifiData.password, band: wifiData.band }, header: { 'Content-Type': 'application/json' }, success: (res) => res.data.code === 0 ? resolve(res.data) : reject(res.data), fail: reject }) }) }

这个封装把wx.request的success和fail用Promise包了一层，后面调用起来更顺手。id为空时后端走新增逻辑，有值时走更新逻辑。密码在传输层要加HTTPS，在存储层建议做哈希或加密，至少不能明文存放。

4. 核心流程实现：从扫码落地页到一键连接的完整代码

4.1 扫码进入后的参数解析：兼容普通二维码、小程序码与q参数

connect页是扫码后的落地页，也是全流程的大脑。进入方式有三种：普通二维码扫入时参数直接放在options里；部分场景微信会把整个URL放在options.q里；小程序码则把参数包在scene字段里。三种入口必须兼容，写代码时先统一提取options再走分支。

Page({ data: { step: 'ready', // ready | connecting | success | fail ssid: '', connectionError: '' }, onLoad(options) { const { storeId, networkId } = this.extractParams(options) if (!storeId || !networkId) { this.setData({ step: 'fail', connectionError: '二维码参数缺失' }) return } this.fetchWifiDetail(storeId, networkId) }, extractParams(options) { if (options.store_id && options.network_id) { return { storeId: options.store_id, networkId: options.network_id } } if (options.scene) { const sceneStr = decodeURIComponent(options.scene) const storeId = sceneStr.match(/store_id=([^&]+)/)?.[1] const networkId = sceneStr.match(/network_id=([^&]+)/)?.[1] return { storeId, networkId } } if (options.q) { const parsed = new URL(decodeURIComponent(options.q)) return { storeId: parsed.searchParams.get('store_id'), networkId: parsed.searchParams.get('network_id') } } return {} } })

这段代码把三种入口统一在一个函数里处理，避免每个页面重复写。options.q分支用了URL对象，基础库较新的版本才支持，旧版本需要手写字符串解析。我的建议是优先获取store_id和network_id两个短参数，配合正则解析即可，不要依赖URL对象，兼容性更好。

4.2 获取WiFi详情并进入连接流程：接口封装与状态流转

拿到标识之后调用后台接口获取WiFi真实信息。这个步骤要前置显示“准备连接”的loading态，让用户知道小程序在干活，而不是卡住了。接口返回后回填SSID到页面，然后自动发起连接流程。

function requestWifiDetail(storeId, networkId) { return new Promise((resolve, reject) => { wx.request({ url: 'https://api.example.com/wifi/detail', method: 'GET', data: { store_id: storeId, network_id: networkId }, success(res) { if (res.data.code === 0) { resolve(res.data.data) } else { reject(new Error(res.data.message || '获取WiFi信息失败')) } }, fail: reject }) }) } async function fetchAndConnect(storeId, networkId) { try { const wifiInfo = await requestWifiDetail(storeId, networkId) await ensureLocationAuth() await resetWifiModule() await connectToWifi(wifiInfo.ssid, wifiInfo.password) const result = await verifyConnection(wifiInfo.ssid) return result } catch (err) { console.error('连接流程异常', err) throw err } }

注意wx.request的success回调里拿到的是res.data，不是res，新手经常在这里多包一层。业务状态码code用0表示成功，实际项目要和后端约定好code语义。用户网络差时wx.request可能长时间挂起，建议在request外层做一个超时控制，比如8秒未返回就提示用户检查网络。

4.3 connectWifi封装：重置模块、平台差异与错误处理

connectWifi的封装函数在第二章给过基础版，这里补充一个关键点：连接之前最好先stopWifi再startWifi，否则部分机型上可能残留上一次连接状态，导致本次连接静默失败。这不是玄学，是WiFi模块的状态机问题。

function resetWifiModule() { return new Promise((resolve, reject) => { wx.stopWifi({ success() { wx.startWifi({ success: () => resolve(), fail: (err) => reject(err) }) }, fail() { // 没初始化过时stopWifi会报错，忽略并继续startWifi wx.startWifi({ success: () => resolve(), fail: (err) => reject(err) }) } }) }) } function connectToWifi(ssid, password) { return new Promise((resolve, reject) => { resetWifiModule() .then(() => { wx.connectWifi({ SSID: ssid, password: password, partialInfo: true, maunal: false, success: (res) => resolve(res), fail: (err) => reject(err) }) }) .catch(reject) }) }

resetWifiModule做了一次容错：stopWifi失败不代表系统有问题，可能模块本来就没启动，所以无论成功失败都继续startWifi。这个写法对真实用户环境更友好。partialInfo在这里设成true，Android上走静默连接，iOS上系统会自动忽略并弹确认框，不需要业务层手动判断平台。

4.4 兜底方案：手动从列表选择WiFi并输入密码

扫码连接是主流程，但总有人扫不出来，二维码磨损，或者人离二维码太远。兜底方案是首页提供“手动选择网络”入口，用户点开后走getWifiList流程，从列表里选一个再输入密码。这个页面和扫码连接共用同一套连接函数，只是数据来源从URL参数变成了用户输入。

function onSelectNetwork(e) { const { ssid } = e.currentTarget.dataset wx.showModal({ title: '输入密码', editable: true, placeholderText: '请输入WiFi密码', success(res) { if (res.confirm && res.content) { connectToWifi(ssid, res.content) .then(() => verifyConnection(ssid)) .then((ok) => { this.setData({ step: ok ? 'success' : 'fail' }) }) } } }) }

showModal的editable模式非常适合这个场景，省去自建输入弹窗的工作量。res.content是用户输入的内容，连接失败后要允许用户重试，不要直接崩溃。这个兜底页做完，整个方案才闭环，扫不了码的人也能手动连上。

5. 避坑：扫码连WiFi最容易踩的6个坑与排查思路

5.1 iOS上partialInfo不生效，总是弹确认框

现象：代码里设了partialInfo: true，Android上顺畅自动连，iOS上每次都弹系统确认框。

原因：iOS从某个版本开始限制第三方App静默连接WiFi，partialInfo被系统忽略。

解决：不要和系统作对。按平台区分：Android用true减少弹窗，iOS用false让用户看到系统弹窗并主动点击允许。UI上要加提示“请在弹窗中点击允许连接”，否则用户可能会漏看。这个差异不是bug，是平台策略。

5.2 二维码扫了没反应，或打开了小程序但页面空白

现象：微信扫普通二维码没有任何反应，或打开了小程序但参数为空。

原因：二维码内容不是合法HTTPS链接，或者URL前缀没有在小程序后台配置“扫普通链接二维码打开小程序”规则，规则未生效。

解决：确认二维码内容是https://开头且域名已备案，到小程序管理后台-开发设置中新增规则，等审核通过后再测试。校验文件放域名根目录，放错位置会校验失败。

5.3 密码里的特殊字符导致连接失败

现象：密码包含&、=、#这类字符，Android上直接连不上，iOS偶尔能连上。

原因：生成二维码URL时没有对参数做encodeURIComponent，&被解析为参数分隔符，密码被截断。

解决：生成URL时统一用encodeURIComponent包裹ssid和password，小程序端解析时统一decodeURIComponent。测试用例里永远包含一个带特殊字符的密码，比如P@ssw0rd&123，用这个当标准测试样本。

5.4 getWifiList返回空数组，但手机系统能看到WiFi

现象：在商场或办公楼里，getWifiList回调返回空数组，系统设置里却能看到一堆WiFi。

原因：小程序在多个页面重复调用getWifiList没有重置WiFi模块，或基础库版本过低导致列表返回失败。另一个隐蔽原因是调用前没有确保位置授权。

解决：每次进入列表页都先stopWifi再startWifi再getWifiList，并确认基础库版本在2.9.0以上。位置授权回调完成后再调用一次列表接口，通常能解决。

5.5 connectWifi成功后立即查询，拿到的是上一次连接的WiFi

现象：connectWifi成功，紧接着getConnectedWifi，返回的是之前连过的WiFi名称。

原因：Android上系统WiFi连接有异步时序，connectWifi的success事件不等于系统连接完成。

解决：延时2至3秒再验证，或者通过wx.onGetWifiList监听列表变化间接判断目标WiFi是否出现，不要贪快。

5.6 老款Android机和小程序基础库的兼容问题

现象：新机上一切正常，某台老Android机上点击连接一直卡在“连接中”。

原因：老款手机驱动和低版本基础库对connectWifi的支持有缺陷，部分伴随定位权限不可用。

解决：增加环境检查，进入页面时读取wx.getSystemInfoSync()的系统版本和基础库版本，版本过低时提示用户用系统相机扫码连接，并提供一个“复制WiFi密码”按钮。这个方案不丢人，保住用户完成连接才是目的。

6. 进阶技巧：连接状态深度校验与多WiFi自动择优

核心连接做完后，真正拉开设体验差距的是两个进阶点：连接状态的深度校验，以及多WiFi场景的自动选优。

深度校验不能只看getConnectedWifi返回的SSID。我在实践中的习惯是，在连接成功后延时2.5秒查一次当前连接，然后请求一个极简的在线检测接口，确认设备确实有网络通路。校验结果直接反馈到UI：成功显示“已连接”，失败显示具体原因，比如“已连上WiFi但无法上网”。

async function deepCheck(ssid) { const connected = await verifyConnection(ssid) if (!connected) return { ok: false, reason: '未连上该WiFi' } // 请求一个轻量检测接口，确认网络通路存在 const pingOk = await new Promise((resolve) => { wx.request({ url: 'https://detect.example.com/ping', method: 'GET', timeout: 5000, success: (res) => resolve(res.statusCode === 200), fail: () => resolve(false) }) }) return { ok: pingOk, reason: pingOk ? '' : '无外网访问' } }

多WiFi场景的自动择优，我一般让后端返回该门店所有网络列表，前端把所有网络的信号强度排序后选最强的一个连接。如果两个网络信号差在5dBm以内，随机选一个，避免所有用户挤在同一台AP上。再叠加频段因素：2.4G信号强但速度慢，5G速度快但衰减快，除非信号差超过10dBm，否则优先连5G的体验更好。这两条策略不需要复杂算法，一个数组排序加几个if就够，但对门店整体网络体验的提升是实打实的。

这套代码写下来，最深的体会是：WiFi的连接成功和真正可用之间隔着太多不可控因素，系统权限、机型差异、路由器策略都可能截胡。把每个环节都当成预期路径去设计，而不是当成异常去捕获，才是这个方案真正稳定的前提。希望这个方向能帮到你。

本文还有配套的精品资源，点击获取