微信小程序从零到上线：开发教程与高频避坑指南

简介：这份资源是面向微信小程序入门与进阶学习者的系统化课程文档，适合希望从零搭建小程序开发知识体系的学生、转行开发者及需要备课参考的教师使用，重点解决环境配置、页面结构、数据绑定与接口调用等基础到实操的衔接问题。资源包共1个文件，为docx格式的详细教程文档，压缩包约15KB，体积轻便，便于在电脑或移动端直接查阅与打印标注。文档内容按开发流程组织，从微信公众平台账号注册、开发者工具下载安装，到新建项目与页面目录结构说明，并逐层讲解app.json全局配置、wxml结构描述、wxss样式布局与js页面逻辑的编写方式。教程还结合可运行的示例展开双向数据绑定与setData更新机制，通过按钮点击弹窗提示演示事件绑定，并给出wx.getLocation等API调用的完整代码片段，最后说明代码提交上传与发布流程。已有354人学习，适合作为动手实践时的随查手册与课堂讲义底稿。

1. 一份 docx 教程能带你走多远：微信小程序从零到上线的完整链路

拿到一份《微信小程序开发详细教程.docx》，很多人的第一反应是——又一份 Hello World 加个按钮的流水账。我照着走了一遍：注册账号、装开发者工具、填 AppID、建项目、写 WXML、绑数据、调 wx.getLocation、最后点上传。走完的结论是，这份课程资源的价值不在代码量，而在于它把微信小程序从注册到审核发布这条链路一次性摊平了，中间没有跳步。新手照着能跑通第一个可提交的小程序；熟手更适合拿它当检查清单，去补自己没走过的环节，比如位置权限被拒、上传后审核打回。它不教你架构，但能让你少在最前面那两天卡住。

2. 环境搭建与项目骨架：AppID、开发者工具和一份必须对齐的目录

2.1 先定 AppID 再动手，顺序反了要返工

教程把「注册公众平台账号」放在第一节，这个顺序是对的，但很多人会跳过它，直接在开发者工具里点「无 AppID 模式」先写代码。无 AppID 确实能建项目、能预览，但真机调试里的部分能力、上传代码、云开发、以及一部分依赖用户身份的接口全都不可用。等到写了半天想真机跑一遍，才发现得回头重建项目，前面调过的路径全要重来。我一般的做法是：第一天就把 AppID 拿到手，哪怕只写一行console.log。

主体类型这件事值得单独说一句，因为它决定了你后面能做到哪一步。个人主体能注册、能开发、能提交审核，但类目和部分能力有边界；如果教程里的示例涉及需要特定类目才开放的能力，用个人号走到一半会卡住。练手用个人号足够，正式项目按实际业务选主体，别等上线前才发现类目对不上。

开发者工具本身有几个安装细节容易被忽略：安装路径不要带中文和空格，Windows 上尤其容易出问题，某些构建环节会因为路径里的空格解析失败；稳定版和预发布版不要同时装两个互相覆盖；工具自带的命令行工具在安装目录下，做自动化预览和上传时用得上。装完先验一下环境：

# 项目根目录下确认骨架完整，-L 2 只看两层，够用 tree -L 2 -a # 确认 Node 与 npm 可用（小程序本身不依赖，但 npm 构建包、TS 模板需要） node -v npm -v

tree的输出应该能看到app.js、app.json、app.wxss和pages/目录。如果只有pages/没有根部的三个文件，说明创建项目时模板没选对，删掉重建比手工补文件快。node -v这步不是必须的，但如果你想用 npm 装第三方组件库，版本太低会失败，建议 14 以上。

2.2 新建项目与四个文件的职责边界

新建项目的对话框里有三个字段要填：项目目录、AppID、项目名称，外加一个「初始化项目模板」的勾选项。模板选「简易项目」就行，它生成的是最小可运行骨架，没有多余的业务代码干扰。选「TypeScript」或者「云开发」模板的话，会多出一批你需要先读懂才能改的文件，对第一次跑通链路反而是负担。

生成出来的目录长这样：

├── pages/ │ └── index/ │ ├── index.js // 页面逻辑，Page() 注册 │ ├── index.json // 页面级配置，会覆盖 app.json 的 window │ ├── index.wxml // 页面结构 │ └── index.wxss // 页面样式 ├── app.js // 小程序逻辑，App() 注册，全局只执行一次 ├── app.json // 全局配置，页面路径必须在这登记 ├── app.wxss // 全局样式，页面可直接使用 ├── project.config.json // 工具配置，不进业务逻辑 └── sitemap.json // 搜索索引配置，默认允许全部索引即可

四个文件的职责边界是最容易搞混的地方。.js里只放逻辑和状态，.wxml里只放结构和绑定表达式，.wxss里只放样式，.json里只放配置。翻车的典型场景是把计算逻辑写进 WXML 的{{}}里，比如{{list.filter(x => x.price > 0)}}，WXML 的表达式能力很弱，不支持函数调用，写进去直接不生效，还不报错。另一个是把样式写成行内style，改一次要动结构文件，维护成本立刻上来。

app.js里的App()全局只执行一次，适合放登录态、全局配置、埋点初始化这类东西。页面里拿全局数据用getApp()，但注意getApp()在App()执行之前调用会拿到undefined，页面onLoad里调用是安全的，更早的时机就不一定。

2.3 app.json 里三个一改就报错的字段

app.json是整份教程里信息密度最高的一个文件。它的字段很多，但真正会一改就白屏或者报错的主要是三个：pages、tabBar、permission与requiredPrivateInfos。

{ "pages": [ "pages/index/index", "pages/detail/detail" ], "window": { "backgroundTextStyle": "light", "navigationBarBackgroundColor": "#ffffff", "navigationBarTitleText": "课程资源示例", "navigationBarTextStyle": "black", "enablePullDownRefresh": true, "onReachBottomDistance": 80 }, "tabBar": { "color": "#8a8a8a", "selectedColor": "#1aad19", "backgroundColor": "#ffffff", "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/detail/detail", "text": "详情" } ] }, "networkTimeout": { "request": 10000, "downloadFile": 15000 }, "permission": { "scope.userLocation": { "desc": "用于展示你附近的课程资源点位" } }, "requiredPrivateInfos": ["getLocation"], "sitemapLocation": "sitemap.json" }

pages数组的第一项就是启动页，顺序不能随意。新增页面必须在这里登记，否则wx.navigateTo跳过去会直接失败，而且错误信息只说页面不存在，不会告诉你要改app.json。这个坑新手几乎必踩一次。

tabBar的list最少两项、最多五项，pagePath必须是pages里已经存在的路径，且不能带查询参数。很多人在pagePath上写pages/index/index?id=1，工具会直接报配置错误。另外，tabBar页面之间跳转要用wx.switchTab，用wx.navigateTo跳tabBar页面会失败，这也是高频翻车点。

permission里的desc是弹窗里展示给用户看的用途说明，不是随便填的备注。审核环节会看这段文案是否写清了用途，写「需要获取位置」这种含糊描述容易被退回，写「用于展示你附近的课程资源点位」就具体得多。至于requiredPrivateInfos，从较新的基础库开始，wx.getLocation这类接口必须在这里声明才允许调用，漏了会直接fail，但错误信息不一定指向配置，容易查偏。

networkTimeout是全局的请求超时，默认值偏长，页面等待感明显。设成 10000 毫秒是个折中值，网络差的时候能早点走fail分支给出提示，而不是让用户对着空白页干等。

3. 页面三件套与数据绑定：WXML、WXSS、JS 各管什么

3.1 WXML 不是 HTML：这几个写法差异必须先记住

WXML 长得像 HTML，但标签体系完全不同，它只有view、text、image、button、input、scroll-view这些内置组件，没有div、span、p。有些教程直接照抄网页代码进去，工具不会报语法错误，但渲染结果是空的——因为不认识的标签会被当成自定义组件处理，找不到对应实现就不渲染。

事件绑定也不是onclick，而是bindtap。bind前缀表示冒泡，catch前缀表示阻止冒泡。传参不能写在事件名后面，得靠><!-- pages/index/index.wxml --> <view class="page"> <!-- 列表渲染：wx:key 用业务唯一字段，别用 index --> <block wx:for="{{courseList}}" wx:key="id"> <view class="course-item">/* pages/index/index.wxss */ .page { padding: 24rpx; background-color: #f5f5f5; min-height: 100vh; } .course-item { display: flex; justify-content: space-between; align-items: center; padding: 28rpx 24rpx; margin-bottom: 16rpx; background-color: #ffffff; border-radius: 12rpx; } .course-price { color: #fa5151; font-size: 28rpx; } .empty { padding: 80rpx 0; text-align: center; color: #999999; font-size: 28rpx; }

什么时候用 rpx、什么时候用 px，判断标准很简单：需要随屏宽等比缩放的（间距、字号、圆角、图标尺寸）用 rpx；需要固定物理尺寸的（1px 边框）用 px。1px 边框用 rpx 写，在高分屏上会被渲染成不到 1 个物理像素，出现时隐时现的「玄学边框」——这是新手最常见的样式困惑之一，原因就在这里。

app.wxss里放全局样式，页面.wxss里放页面私有样式。注意页面样式默认是页面级作用域，不会污染其他页面，但app.wxss里的类名是全局生效的。所以全局样式里只放page、container这类通用容器和重置样式，业务类名一律写到页面文件里，否则项目稍微大一点就会出现「改了 A 页面，B 页面样式也变了」。

3.3 setData 的路径写法和性能注意

数据绑定是单向的：data变 → 视图变。想让视图变，唯一的方式是调用this.setData()。直接写this.data.message = 'xxx'数据确实变了，但视图不会更新，因为setData内部除了赋值还负责把数据从逻辑层传到渲染层。这是小程序和普通前端框架差异最大的一点，也是从 Vue/React 转过来的人最容易踩的坑。

// pages/index/index.js Page({ data: { keyword: '', courseList: [] }, onLoad() { this.fetchCourses() }, onSearchInput(e) { // e.detail.value 是输入的当前值，直接回写即可 this.setData({ keyword: e.detail.value }) }, onCourseTap(e) { // dataset 里的值来自>// 位置获取：先查授权，再调用，fail 分支给出可理解的提示 Page({ data: { locationText: '未获取' }, getLocation() { wx.getSetting({ success: (setting) => { const authorized = setting.authSetting['scope.userLocation'] // 用户之前明确拒绝过，只能引导他去设置页手动打开 if (authorized === false) { wx.showModal({ title: '需要位置权限', content: '用于展示附近的课程资源点位，请在设置中开启', confirmText: '去设置', success: (res) => { if (res.confirm) { wx.openSetting() } } }) return } this.doGetLocation() }, fail: () => { // 拿不到授权状态时，直接尝试调用，让系统弹窗兜底 this.doGetLocation() } }) }, doGetLocation() { wx.getLocation({ type: 'gcj02', // gcj02 可直接给 openLocation 用；wgs84 适合传给第三方地图服务 isHighAccuracy: true, // 开启高精度，室内定位更稳，但耗时更长 highAccuracyExpireTime: 4000,// 高精度定位的超时，超过后回退到普通精度 success: (res) => { this.setData({ locationText: `${res.latitude.toFixed(6)}, ${res.longitude.toFixed(6)}` }) }, fail: (err) => { // 常见 errMsg：getLocation:fail auth deny / system permission denied console.error('getLocation fail', err) wx.showToast({ title: '定位失败，请检查权限设置', icon: 'none' }) } }) } })

参数上最需要说清的是type。wgs84是国际坐标系，gcj02是国内加密坐标系。如果拿到坐标之后要调wx.openLocation打开地图，必须用gcj02，传wgs84会出现几百米的偏移，看起来像「地图定位不准」，其实是坐标系搞混了。isHighAccuracy打开后会多花一点时间，但室内场景的漂移会小很多；highAccuracyExpireTime是它的超时上限，设 4000 毫秒是个比较稳的值，设太短等于没开。

还有一步容易被跳过：app.json里的permission.scope.userLocation.desc和requiredPrivateInfos必须同时配好。只配permission不配requiredPrivateInfos，接口直接fail；只配requiredPrivateInfos不配permission，弹窗文案缺失，审核阶段容易被打回。这两项是成对出现的。

4.2 网络请求收口：别在每个页面里各写一遍 wx.request

wx.request是最常用的 API，也是最容易写散的一个。教程示例里通常直接在一个页面方法里调，能跑通，但项目一旦有三个以上页面要请求数据，就会出现域名拼接不一致、错误处理不一致、loading 状态重复写的问题。我一般会在项目里放一个utils/request.js统一收口。

// utils/request.js const BASE_URL = 'https://your-domain.com/api' // 换成自己的域名，需在小程序后台配置 function request({ url, method = 'GET', data = {}, header = {}, showLoading = true }) { if (showLoading) { wx.showLoading({ title: '加载中', mask: true }) } return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + url, method, data, header: { 'content-type': 'application/json', ...header }, timeout: 10000, success: (res) => { // HTTP 200 不代表业务成功，要按自己的返回结构判断 if (res.statusCode >= 200 && res.statusCode < 300 && res.data.code === 0) { resolve(res.data.data) } else { reject(new Error(res.data && res.data.message ? res.data.message : '业务异常')) } }, fail: (err) => { // 断网、域名未配置、证书问题都会落到这里 reject(err) }, complete: () => { if (showLoading) { wx.hideLoading() } } }) }) } module.exports = { request }

几个参数值得解释。timeout写在单次请求里会覆盖app.json的networkTimeout.request，做上传下载这类慢接口时单独放宽更合理。mask: true让 loading 遮住页面，防止用户在请求过程中重复点击；但也别所有请求都开，列表下拉刷新时开遮罩体验很差，所以留了showLoading开关。complete里关 loading 而不是success里关，是为了fail和异常路径也能关掉，否则一次请求失败，loading 就永远挂在那里转，用户只能杀掉小程序重进——这个 bug 我见过不止一次。

封装成 Promise 之后，页面里可以配合async/await写，错误处理用try/catch收在一起，比层层嵌套回调清楚得多。要上传代码之前，记得把BASE_URL换成正式域名，并且这个域名必须在小程序后台的「开发设置」里配置好，只支持 HTTPS。

4.3 域名与合法性的三道门

请求类 API 能不能通，取决于三道门是否都过了。第一道是域名协议，必须是 HTTPS，HTTP 一律不通。第二道是后台配置，request合法域名、uploadFile合法域名、downloadFile合法域名是分开配的，只配了request去调wx.downloadFile，照样失败。第三道是工具里的「不校验合法域名」开关，它只在开发阶段有效，勾上之后本地能通，真机和线上环境依然按正式规则校验。

这三道门里最容易误判的是第三道。开发时勾了开关，一切正常，上传体验版之后接口全挂，报url not in domain list，回头看代码怎么都找不到问题。我的习惯是：开发阶段开关可以勾，但每天晚上把开关取消一次，用真机跑一遍核心链路，把问题暴露在提交审核之前。这个动作花不了几分钟，能省掉一轮审核驳回。

5. 避坑与排查：提交审核前最容易翻车的五处

5.1 界面与交互类：白屏、样式错位、点不动

现象一：真机预览白屏，工具里却正常。原因通常有两类：一是启动页路径在pages里写错或者顺序不对，二是首页的onLoad里同步抛了未捕获的异常，渲染流程直接中断。工具的模拟器有容错，真机没有。解决方式是先在工具里打开调试器看 Console，把onLoad里第一行打印加上，确认代码执行到了哪一步，再逐段注释定位。

现象二：给元素写1px边框，在部分机型上时有时无。原因是用了rpx写边框，缩放到高分屏后不到一个物理像素，渲染结果不稳定。解决方式是把所有 1px 边框改成px单位，或者用transform: scaleY(0.5)做半像素方案。这个坑不致命但很烦人，属于典型的「玄学」问题，知道原因就一句话的事。

现象三：tabBar图标在工具里显示，真机上不显示。原因基本是图标路径写成了网络地址或者绝对路径，tabBar的iconPath只接受项目内的相对路径，并且图标文件建议控制在 40KB 以内。解决方式是把图标放到项目目录下，路径写images/tab-home.png这种形式，不要以/开头。

5.2 数据与事件类：改了没反应、传参对不上

现象四：this.data.xxx = 'yyy'之后页面纹丝不动。原因是绕过了setData，逻辑层数据变了但渲染层收不到通知。这个问题在从其他框架转过来的人身上出现频率极高，因为this.data是可直接读写的，语法上完全合法，不报错。解决办法是全局搜一遍this.data.的赋值语句，全部改成this.setData({})。如果只是需要读值做判断，读this.data没问题，只有写才必须走setData。

现象五：列表点击取到的id和预期类型不一致，条件判断永远为假。原因是style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />