简介这是一份面向小程序初学者的微信小程序开发入门教程文档以DOCX格式整理系统覆盖从环境搭建到最终发布上线的完整开发流程。内容从注册微信公众平台账号、安装微信开发者工具入手逐步讲解项目创建、目录结构解析、app.json全局配置以及页面开发中的WXML结构、WXSS样式和JS逻辑编写并对数据绑定给出Mustache语法与setData方法的对照示例演示了wx.request网络请求和wx.getLocation获取用户位置等常用API调用方式末尾还整理了代码上传与发布的操作要点。资源为单个DOCX文档约15KB便于直接阅读与后续标注学习目前已有353人在线学习。文档结构清晰、代码示例完整适合计划入门微信小程序开发或需要快速梳理开发流程的读者边看边练。1. 微信小程序教程文档拆解先看它能不能帮你把 demo 真跑起来收到《微信小程序开发详细教程.docx》之后很多人关心的是照着它走能不能把微信小程序真正跑起来并发布上线。整套资源线路完整从注册公众平台、安装微信开发者工具到创建项目、写页面、做数据绑定、调 API再到上传审核和发布一条链路全串齐了。它适合零基础转前端的从业者也适合要快速交付展示型页面的开发者。文档本身是按标准路径写的但环境细节没有完全展开AppID 的三种来源有什么差异、定位接口为什么必须配隐私声明、网络请求的域名白名单卡在哪。这些恰恰是照着抄报错率最高的地方。下文把每一步拆开把参数讲清楚再把新手容易翻车的坑提前标出来。2. 环境与工程初始化从注册到生成第一个空白页面2.1 注册账号与选型个人主体、企业主体和三种 AppID 来源注册微信公众平台账号时入口选小程序类型主体类型要在动手前定下来。个人主体注册快、成本低适合练手和展示型应用但支付能力、部分用户通知能力用不了企业主体能调用更完整的服务能力但要营业执照和认证认证有一笔费用。选错主体后期迁移代价很高我一般建议先想清楚交付对象再注册而不是先注册再纠结。真正决定能不能真机预览、上传和发布的是 AppID。新建项目时开发者工具提供三种来源正式 AppID、测试号、游客模式。三者的能力边界差异很大很多人拿着测试号玩了半天最后发现真机预览绕不过去只能回头重新注册。AppID 来源能做什么不能做什么正式 AppID真机预览、上传、发布、调用完整 API需要先完成公众平台注册测试号在开发者工具模拟器里编译调试真机预览、上传、发布游客模式快速浏览项目结构大部分 API 不可用、无法真机预览很多入门教程会建议先用测试号跑通逻辑我的习惯是注册完直接填正式 AppID。中途替换 AppID 不是改一个字段就结束project.config.json、上传记录、体验版成员都要跟着重新配置隐性成本不低。开发者工具里切换 AppID 的位置在菜单栏“详情-基本信息”也可以直接编辑 project.config.json 的 appid 字段。{ appid: wx1234567890abcdef, compileType: miniprogram, libVersion: 3.4.3, setting: { es6: true, postcss: true, minified: true }, projectname: demo-app }appid 是账号标识填成测试号时工具只允许模拟器编译compileType 保持 miniprogram 即可libVersion 是基础库版本新项目用当前稳定版老项目不要轻易跨大版本升级setting 里的 es6 开关对应工具的“ES6 转 ES5”选项低版本手机能不能跑起来就看它。团队里新拉下来的项目编译报错先检查这个文件不要急着翻业务代码。2.2 新建项目与目录结构四件套各自的责任边界新建项目时项目目录建议选英文路径比如工程目录下建个 miniapp/demo。中文路径或者带空格的路径在部分 Windows 环境里会出现编译缓存找不到模块的玄学报错我遇到过几次工具卡在 Compiling 界面换目录后恢复正常。初始化模板时勾选“简易项目”工具会生成一个最小可运行的页面集合比空白模板更适合看清文件关系。生成后的项目是标准四件套结构app.js、app.json、app.wxss 和 pages 目录。每个页面由四个文件组成文件名和页面目录名保持一致开发者工具靠同名约定把页面四件套关联起来。把下面这张表记住后面排错时能少走很多弯路。文件职责app.js小程序入口逻辑onLaunch 里做全局初始化app.json全局配置页面注册、窗口表现、tabBar、权限声明app.wxss全局样式作用于所有页面pages/index/index.js页面逻辑data、事件、生命周期pages/index/index.json页面级配置可覆盖全局窗口配置pages/index/index.wxml页面结构类 XML 语法pages/index/index.wxss页面样式只作用于当前页面注意页面 json 是可以省略的文件缺失时自动继承全局配置但每个页面最好都补上哪怕只是一个空对象这样单独调整某个页面的导航栏颜色时不会影响其他页面。app.json 里还支持 sitemap 配置基础库版本较新的项目会默认生成 sitemap.json内容涉及搜索收录新手可以先忽略不影响本地开发和发布。2.3 app.json 全局配置pages 数组顺序就是编译入口顺序app.json 的 pages 数组是项目里最容易被忽略的一段配置。数组第一项决定编译后的首页数组顺序同时也是页面跳转时的注册顺序。常见错误是手动新增页面后忘了在这里登记工具编译不报错但运行时跳转直接白屏后面避坑章节会专门展开。window 对象统一控制导航栏和窗口表现。navigationBarBackgroundColor 配导航栏背景色navigationBarTitleText 是显示在顶部的标题navigationBarTextStyle 只支持 black 和 white 两个值backgroundTextStyle 控制下拉背景的明暗。位置类页面。做了 tabBar 的话导航栏颜色和 tabBar 选中色建议保持同一主题色视觉上更统一也给审核人员留下“这页面是完整设计过”的印象。{ pages: [ pages/index/index, pages/list/list ], window: { navigationBarBackgroundColor: #1aad19, navigationBarTitleText: 演示项目, navigationBarTextStyle: white, backgroundTextStyle: light }, tabBar: { color: #999999, selectedColor: #1aad19, list: [ { pagePath: pages/index/index, text: 首页 }, { pagePath: pages/list/list, text: 列表 } ] } }tabBar 的 list 最少 2 项、最多 5 项pagePath 必须是 pages 数组里已经注册的路径color 是未选中文字色selectedColor 是选中态颜色。不配 iconPath 也能正常显示纯文字 tab适合早期快速验证。navigationBarTextStyle 只有两个取值配了浅色导航栏背景必须选 black否则标题字色会和背景糊在一起。保存 app.json 之后工具会自动重新编译如果首页顺序不对直接看这里不需要动代码。3. 页面开发与数据绑定WXML、WXSS、JS 三件套怎么配合3.1 WXML 结构与事件bindtap、catchtap 和>view classcontainer text classtitle{{message}}/text view classlist view wx:for{{items}} wx:keyid classlist-item bindtaponItemTap >Page({ data: { items: [], message: 数据绑定示例 }, onLoad() { const list [ { id: 1, name: 条目A }, { id: 2, name: 条目B } ]; this.setData({ items: list }); }, onItemTap(e) { const { id, index } e.currentTarget.dataset; this.setData({ [items[${index}].name]: 已点击 }); wx.showToast({ title: 点击了 id, icon: none }); }, onTapDemo() { this.setData({ message: 按钮被点过了 }); } });上面代码里用模板字符串拼 setData 的路径items[${index}].name表示精确更新数组中某一项的 name 字段数据量大时性能比整体替换好。showToast 的 icon 传 none 表示只显示文字不显示图标传 success 会带对勾loading 会带转圈且需要手动关闭。另外 setData 单次传输的数据量有上限把整张表、整段富文本一次性塞进去低端机上会出现明显卡顿甚至渲染白屏列表分页、图片走 URL 是常规做法。3.3 样式与单位rpx 适配和真机安全区WXSS 与 CSS 大部分语法一致差异集中在几个点上。rpx 是自适应单位任何屏幕都按 750rpx 宽度折算iPhone 375px 宽度下 1rpx 等于 0.5pxAndroid 360px 宽度下约 0.48px写盒子和间距优先用 rpx。vh 在真机上能正常取到视口高度但 iPhone 底部的小黑条区域需要单独做安全区适配否则底栏内容会被遮挡。.container { display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; padding-bottom: env(safe-area-inset-bottom); box-sizing: border-box; } .list-item { width: 690rpx; margin: 16rpx auto; padding: 24rpx; background: #ffffff; border-radius: 12rpx; } button { background: #1aad19; color: #ffffff; border-radius: 8rpx; } button::after { border: none; }容器用 min-height 而不是 height防止内容超出时容器被撑出屏幕出现二次滚动条padding-bottom 用env(safe-area-inset-bottom)处理底部安全区这是发布后真机展示最容易漏掉的一步。button 默认自带灰色边框覆盖样式时必须同时处理 button::after否则你写的圆角和背景都生效了外圈灰色边框还在。rpx 的坑在于字体和固定尺寸元素混用时换算不一致图标、间距用 rpx单行字体直接用 px 保持设计稿精度混用前先定好统一规则。4. 常用 API 调用与权限配置getLocation 与 request 的完整前置条件4.1 getLocation定位接口的两个前置声明漏一个就 fail文档里给的 wx.getLocation 直调写法在较新的版本里大概率会失败。定位属于隐私接口需要同时满足几个条件app.json 里配置 permission 声明用途requiredPrivateInfos 里列出 getLocation公众平台后台的“用户隐私保护指引”也要勾选位置信息相关项。缺一个fail 回调里就会看到类似getLocation:fail the api need to be declared in requiredPrivateInfos field的报错。{ pages: [pages/index/index], permission: { scope.userLocation: { desc: 用于在地图上展示你的位置 } }, requiredPrivateInfos: [getLocation] }permission 下面的 desc 会直接显示在微信授权弹窗里文案要写真实业务用途后台审核会看这个字段和实际行为是否匹配requiredPrivateInfos 声明具体用到哪些隐私接口。配置顺序建议先把代码里的 app.json 改好再去后台补隐私保护指引最后重新编译授权弹窗才会正常弹出。授权拒绝之后fail 分支里要给出明确提示不能只让按钮没反应。Page({ data: { location: }, getLocation() { wx.getLocation({ type: gcj02, isHighAccuracy: true, success: (res) { const { latitude, longitude } res; this.setData({ location: 纬度${latitude.toFixed(6)}经度${longitude.toFixed(6)} }); }, fail: (err) { console.error(getLocation failed, err); wx.showToast({ title: 定位失败请检查授权, icon: none }); } }); } });type 用 gcj02 而不是 wgs84wgs84 是 GPS 原生坐标直接在腾讯地图、高德这类国内地图服务里渲染会出现几百米偏移gcj02 是国内通用的火星坐标系。isHighAccuracy 只对 Android 生效会额外增加电量消耗非连续定位场景建议不开。success 回调里用箭头函数this 指向页面实例避免在普通 function 里丢了上下文导致 setData 报错。定位结果先 toFixed 再展示经纬度小数位数太多在部分机型上会显示成科学计数法。4.2 wx.request域名白名单、method、timeout 的边界wx.request 最常翻车的点不在代码而在域名。正式环境下请求地址必须在小程序后台配置成 request 合法域名而且只能是 https开发阶段可以在开发者工具右上角“详情-本地设置”里勾选“不校验合法域名”绕过校验但这个开关只对工具模拟器有效真机预览时后台没有配置的域名照样进 fail。域名不能带端口不能用 IPhttps 证书链路必须完整这些是白名单校验的硬条件。wx.request({ url: https://your-domain.com/api/v1/list, method: POST, header: { content-type: application/json, X-Auth-Token: token-value }, data: { page: 1, size: 20 }, timeout: 10000, success: (res) { if (res.statusCode 200) { const list res.data.data || []; this.setData({ items: list }); } else { console.warn(业务状态异常, res.statusCode, res.data); } }, fail: (err) { console.error(request failed, err); wx.showToast({ title: 网络异常, icon: none }); }, complete: () { wx.hideLoading(); } });method 常用 GET 和 POST幂等查询用 GET提交类操作用 POST。header 里的 content-type 按实际请求体格式填传 JSON 用 application/json传表单用 application/x-www-form-urlencoded。timeout 单位是毫秒默认 60 秒偏长接口在弱网下等十几秒没有反馈用户早就走了我一般设 10 秒并配合 fail 提示。success 只代表请求到达并返回了业务是否成功要看 statusCode 和返回体里的业务码两层判断都要写。complete 无论成败都会执行适合在这里关 loading避免接口秒回时转圈一直不消失。提示本地联调用“不校验合法域名”没问题正式评审前必须把代码里的域名全部换成后台已配置的 https 白名单并全局搜一遍有没有残留测试地址。4.3 页面生命周期与数据刷新onLoad 和 onShow 怎么分工页面首次进入的执行顺序是 onLoad、onShow、onReady之后从后台切回来只走 onShow从其他页面返回当前页也不会重新走 onLoad。这个差异决定了两类请求的落点初始化数据放 onLoad 只拉一次依赖页面可见状态的数据放 onShow。列表页常见的组合是 onLoad 首拉onShow 回来时按条件刷新避免切后台再回来时数据还是旧的。方法触发时机典型用途onLoad页面首次加载初始化数据请求onShow首次加载后、从后台切回刷新可见数据onReady初次渲染完成操作页面节点onHide切后台、跳转其他页面暂停轮询、动画onUnload页面销毁清理定时器和监听Page({ data: { items: [], loading: false }, onLoad() { this.loadList(); }, onShow() { if (this.data.items.length) { this.loadList(); } }, loadList() { this.setData({ loading: true }); // 这里放 wx.request成功后 setData 更新 items 并隐藏 loading // 失败时也要隐藏 loading并给出可重试的提示 } });onShow 里用 if 判断 items.length是为了避免和 onLoad 首拉重复请求首次进入时 onShow 紧跟 onLoad 触发此时 items 为空不会二次请求从后台切回来时 items 已经有值才触发刷新。这个写法在列表页、订单页里很通用。onHide 适合停掉轮询和动画onUnload 里清定时器内存泄漏大多是把 setInterval 挂在页面级又没在页面销毁时清理。5. 避坑与排查清单新手最容易翻车的五个点5.1 测试号能编译、真机预览却白屏现象用测试号 AppID 创建项目工具模拟器一切正常点预览扫码后小程序一直加载或者直接白屏。原因测试号只面向开发者工具模拟器没有绑定真实小程序账号真机预览和上传都依赖正式 AppID。解决在公众平台完成注册取得正式 AppID在菜单栏“详情-基本信息”里替换或者新建项目时直接填入正式 AppID。习惯上我会在新建项目时把这个字段先填对后面体验版、上传记录都不会带历史包袱。5.2 新增页面后编译通过、跳转却白屏现象手动在 pages 目录下新建了 list 文件夹和四个文件工具编译正常但运行时 wx.navigateTo 跳转后页面空白控制台提示页面未注册。原因app.json 的 pages 数组不会自动同步手动新建的页面工具只认数组里已登记的路径。右键菜单新建页面会自动写入手动建目录则不会。解决在 app.json 的 pages 数组补上pages/list/list保存后工具自动重新编译。养成习惯新增页面后第一件事是去 pages 数组登记而不是先写页面代码少一次白屏排查。5.3 setData 直接赋值视图怎么都不刷新现象代码里写了this.data.list.push(...)控制台打印数据有值页面却不更新下拉也没有新内容。原因视图层的数据更新必须由 setData 驱动直接改 data 只是改了逻辑层内存对象视图层收不到通知。这是小程序数据流和普通 JavaScript 最大的区别。解决先构造新数组再 setData局部更新时用数据路径。// 错误写法只改了内存视图不刷新 // this.data.list.push(newItem); // 正确写法生成新数组整体更新 const next this.data.list.concat(newItem); this.setData({ list: next }); // 只更新某一项时走路径 this.setData({ list[0].name: 新名字 });concat 返回新数组不修改原引用配合 setData 的传输机制更保险路径更新避免整个数组重新序列化列表超过几十项时能明显感觉到滚动流畅度的差异。排查时先看控制台有没有 setData 相关的报错再看传输的数据量是不是接近单次上限。5.4 wx.request 在工具里正常、真机上一直 fail现象开发者工具勾了不校验域名接口请求成功扫码真机预览后同样的请求全部进 fail 回调控制台报 url not in domain list。原因工具里的“不校验合法域名”只对工具模拟器生效真机预览走后台的服务器域名校验另一种常见情况是域名本身是 http或者 https 证书不完整。解决开发阶段保持工具勾选跳过校验真机联调时把接口域名加到后台“开发管理-服务器域名-request 合法域名”必须 https、不能带端口、不能是 IP。联调结束后再全局搜一遍代码里的 baseURL确认没有测试域名残留。5.5 旧设备白屏或语法报错现象同一份代码新手机正常旧安卓机或低版本微信打开直接白屏控制台报类似 Cannot read property 的错误或者模板字符串、箭头函数直接报语法错误。原因低版本基础库环境不支持部分新语法和新 API开发者工具的转译设置没有完全覆盖低版本场景。解决在开发者工具“详情-本地设置”里打开 ES6 转 ES5基础库版本不要设置得太激进。用到较新 API 时先做存在性判断不要直接调用。if (typeof wx.getClipboardData function) { wx.getClipboardData({ success(res) { console.log(res.data); } }); } else { console.warn(当前基础库不支持该 API); }API 存在性判断比单纯查版本号更稳版本号只能告诉你大概区间某个 API 从哪个基础库引入还是要翻文档而 typeof 判断可以在边界环境里直接兜住。处理完记得清缓存重新编译很多低版本问题在工具里根本复现不出来真机样机样本越多越好。6. 发布前验证体验版、接口环境核验与审核那点事6.1 上传前自检与体验版验证代码写完后点开发者工具右上角“上传”填版本号和备注代码会出现在公众平台后台的版本管理里。此时不要急着提交审核先在版本管理里生成体验版二维码用一个测试手机完整扫一遍验证登录、列表、详情、提交这四个主干功能。体验版和正式版的代码产物基本一致体验版能走通审核阶段因为功能问题被打回的概率会小很多。6.2 接口环境核验与第一人称教训我翻过一次车做一个展示型小程序时本地联调一直连测试接口交付前忘了切回正式地址打包上传的体验版所有列表拉的全是测试数据演示现场当场露馅。从那以后我每次上传前都强制过一遍接口环境核验全局搜 baseURL确认没有 test、staging 字样真机连体验版验证登录、列表、详情三条主链路核对 app.json 里的权限声明和授权弹窗文案截图留存版本号与发布时间。这套检查在多人协作时尤其重要因为测试地址可能不止一个人在改。希望帮到你。本文还有配套的精品资源点击获取