1. 为什么“从0开始做小程序”这件事比大多数人想的更值得重做一遍“手把手教你做微信小程序”——这个标题在技术社区里出现的频率大概和“零基础学Python”一样高。但真正能让人做完之后心里踏实、手上能用、后续敢接活儿的教程少之又少。我带过几轮前端新人训练营也帮某高校实验室做过三版教学Demo发现一个反复出现的现象90%的人卡在“创建完项目就卡住”不是因为不会写代码而是根本没搞清小程序到底是什么结构、它和网页的根本差异在哪、哪些东西必须现在就理解、哪些可以先跳过。比如很多人一上来就猛敲app.js改onLaunch调wx.request结果连页面跳转都报错“Page is not defined”。再比如看到pages/index/index.wxml里写个view就以为和HTML一样结果发现div不能用、class要写成class但样式文件却叫.wxss、数据绑定用{{}}但不能直接写{{user.name}}——这些不是“语法细节”而是小程序运行机制的外在表现。你跳过原理硬抄代码就像没学过电路就焊主板表面通电一加负载就冒烟。这次我们不走“复制粘贴→点运行→截图发朋友圈”的捷径。我们要回到最原始的状态打开微信开发者工具新建一个空项目然后像第一次接触编程那样逐行看懂每一类文件的作用、每一个API调用背后的生命周期、每一个配置项的真实约束。你会看到app.json不只是“页面路径列表”它是整个小程序的路由中枢和能力开关project.config.json不是可有可无的IDE配置它决定了你的代码在真机上能不能被识别为合法小程序而sitemap.json这种看似冷门的文件恰恰是决定你的内容能否被微信搜索收录的关键闸门。这不是教你怎么做一个“好看的商城首页”而是帮你把小程序的底层骨架摸透。当你清楚知道App()实例在什么时候初始化、Page()对象在什么时机触发onLoad、setData为什么不能直接赋值对象、wx:for循环里的index和item变量从哪来——你才真正拿到了这把钥匙。后面无论做预约系统、内部审批流还是轻量级问卷工具你都不再是“拼凑功能”而是“按需组装”。提示本文所有操作均基于微信官方最新稳定版开发者工具v1.06.2403140与基础库 3.4.8。不依赖任何第三方框架如Taro、UniApp所有代码均为原生写法。你不需要提前装Node、不用配Webpack甚至不需要会ES6——但你要愿意暂停5分钟把app.js里那三行注释读完。2. 真正的“从0开始”不是新建项目而是理解项目结构的四层契约很多教程说“点击‘新建项目’→填AppID→选模板→完成”这确实是一键生成。但生成的那一刻你其实已经签下了四份隐性契约——它们不写在界面上却决定了你后续每一步能不能走通。忽略其中任何一份都会在某个深夜调试时让你对着控制台里一行红色报错发呆半小时。2.1 第一层契约project.config.json—— 开发者工具的“身份证”这是你新建项目后第一个该打开、也是最容易被忽略的文件。它不在项目目录里显示为“源码”而是藏在项目根目录下由开发者工具自动生成。它的核心作用是告诉IDE“我是谁、我在哪开发、我允许谁调试我”。{ description: 项目配置文件, packOptions: { ignore: [] }, setting: { urlCheck: true, es6: true, enhance: true, postcss: true, minified: true, newFeature: true, coverView: true, nodeModules: false, autoAudits: false, showShadowRootInWxmlPanel: true, scopeDataCheck: false, uglifyFileName: false, checkInvalidKey: true, checkSiteMap: true, uploadWithSourceMap: true, compileHotReLoad: false, useMultiFrameRuntime: true, useApiHook: true, babelSetting: { ignore: [], disablePlugins: [], outputPath: } }, compileType: miniprogram, libVersion: 3.4.8, appid: wx1234567890abcdef, projectname: my-first-miniprogram, debugOptions: { hidedInDevtools: [] }, isGameTourist: false, simulatorType: wechat, simulatorPluginLibVersion: , condition: { search: { current: -1, list: [] }, conversation: { current: -1, list: [] }, game: { currentL: -1, list: [] }, miniprogram: { current: -1, list: [] } } }重点看三个字段appid不是随便填的。如果你填的是测试号以wx开头的16位字符串它只在本机有效如果填的是企业认证后的正式AppID那么你本地调试时所有网络请求、登录态、支付接口都会走真实环境——这意味着你可能在改一个按钮颜色时意外触发了真实订单创建。实操心得新人务必用测试号起步AppID可在微信公众平台后台“开发管理→开发设置”中获取无需认证。libVersion这是基础库版本。微信客户端会自带一个基础库你的代码必须兼容它。比如你写了wx.getSystemInfoSync().safeArea但用户手机微信版本太低基础库2.7.0这个属性就不存在。避坑经验在app.json里通过requiredBackgroundModes等字段声明能力时必须确认对应基础库版本支持。官方文档每个API下方都标有“最低基础库版本”别跳过。setting.urlCheck默认为true意味着所有wx.request请求的域名必须在“开发管理→服务器域名”中白名单备案。但注意本地调试时这个检查是关闭的。所以你本地能通的接口一上传体验版就404——因为线上环境强制校验。关键提醒每次提审前务必在开发者工具右上角“详情→本地设置”里勾选“不校验合法域名”模拟真实环境跑一遍。2.2 第二层契约app.json—— 小程序的“宪法性文件”如果说project.config.json是给IDE看的那app.json就是给微信客户端看的。它定义了小程序的“存在形式”有多少页面、顶部导航长什么样、是否允许下拉刷新、能不能分享……它不写一行逻辑却掌控全局。{ pages: [ pages/index/index, pages/logs/logs ], window: { navigationBarTitleText: 我的第一个小程序, navigationBarBackgroundColor: #ffffff, navigationBarTextStyle: black }, tabBar: { list: [{ pagePath: pages/index/index, text: 首页, iconPath: assets/icons/home.png, selectedIconPath: assets/icons/home-active.png }, { pagePath: pages/logs/logs, text: 日志, iconPath: assets/icons/logs.png, selectedIconPath: assets/icons/logs-active.png }] }, style: v2, sitemapLocation: sitemap.json, lazyCodeLoading: requiredComponents }这里藏着三个极易踩的深坑页面路径必须精确到.js文件且大小写敏感。pages/index/index对应的是pages/index/index.js而不是pages/Index/Index.js。Windows系统不区分大小写但iOS真机严格区分——你本地跑得好好的一发体验版首页就白屏。实操技巧在开发者工具里右键页面文件夹→“在资源管理器中显示”确认路径名完全一致。tabBar的iconPath路径是相对于app.json所在位置的。也就是说assets/icons/home.png实际指向的是项目根目录下的assets/icons/home.png。但如果你把图标放在pages/index/assets/下写成pages/index/assets/home.png就会报错“找不到图标”。原因tabBar图标加载时机早于页面渲染此时页面级路径尚未生效。解决方案所有tabBar图标统一放在assets/或static/这样的根级目录。style: v2这个字段决定了你使用的是新版组件样式。如果你删掉它或者写成v1那么所有button、input的默认样式会回退到2018年的老样子——圆角消失、阴影变淡、字体变小。但更重要的是某些新API如wx.openSetting返回的authSetting结构在v1模式下不返回完整字段。经验总结除非维护超老项目否则永远保留style: v2。2.3 第三层契约app.js—— 全局状态与生命周期的“总控室”app.js是小程序的入口文件但它不像网页的main.js那样负责启动一切。它的核心职责只有两个管理全局数据、监听全局生命周期事件。很多人在这里塞满业务逻辑结果导致页面间通信混乱、状态难以追踪。// app.js App({ // 全局数据所有页面可通过 getApp() 访问 globalData: { userInfo: null, version: 1.0.0, apiBase: https://api.example.com }, // 小程序初始化完成时触发全局仅一次 onLaunch(options) { console.log(小程序启动, options); // 此处适合做检查登录态、获取设备信息、预加载公共配置 }, // 小程序进入前台时触发包括从后台切回、从桌面图标启动 onShow(options) { console.log(小程序显示, options); // 此处适合做检查token过期、同步用户信息、上报场景值 }, // 小程序进入后台时触发 onHide() { console.log(小程序隐藏); // 此处适合做清理定时器、暂存未提交表单 }, // 小程序发生脚本错误或API调用失败时触发 onError(err) { console.error(全局错误, err); }, // 小程序有未处理的Promise rejection时触发 onUnhandledRejection(res) { console.warn(未捕获的Promise异常, res); } });关键点解析globalData不是响应式数据。你改了getApp().globalData.userInfo {name: 张三}已打开的页面不会自动更新视图。正确做法用wx.setStorageSync存本地缓存页面onLoad时读取或用EventChannel、pubsub等事件机制通知页面更新。onLaunch的options参数包含了小程序的启动参数。比如用户从微信群链接点击进来options.scene会是1089从公众号菜单进入options.query里会有?frommp。实战价值你可以根据scene值动态展示不同欢迎页实现精准运营。onShow的options比onLaunch更丰富。它包含scene、query、shareTicket转发卡片、referrerInfo来源小程序等。重要提醒onShow会频繁触发比如用户切到微信聊天再切回来所以里面不要放耗时操作如wx.request。应加节流或判断状态后再执行。2.4 第四层契约sitemap.json—— 决定你的内容能否被微信搜索“看见”这个文件常被当成摆设但它其实是小程序SEO的命门。微信搜索会爬取你的页面但前提是你得明确告诉它“哪些页面允许被抓取”。{ desc: 关于本小程序的搜索描述, rules: [{ action: allow, page: * }, { action: disallow, page: pages/logs/logs }] }规则很简单action: allow表示允许索引该页面action: disallow表示禁止索引page: *是通配符代表所有页面page: pages/index/index则特指首页。致命误区很多人以为只要页面有内容微信就能搜到。错。微信搜索只索引sitemap.json中allow的页面且该页面必须满足① 页面wxml中有足够文本内容非纯图片②wx:for循环的数据已真实渲染不能是空数组③ 页面onLoad中调用了wx.setNavigationBarTitle等API证明它是“活跃页面”。实测结论如果你的小程序目标是获客如本地服务、知识付费首页、商品列表页、详情页必须allow用户中心、设置页、日志页这类纯功能页建议disallow。上线前务必在微信公众平台“推广中心→微信搜索”里提交sitemap否则即使配置正确也可能延迟数天才被收录。3. 页面级真相WXML、WXSS、JS、JSON 四件套的分工与默契当你在app.json里写下pages/index/index微信客户端就会去加载四个同名文件index.wxml、index.wxss、index.js、index.json。它们不是随意组合而是遵循一套精密的协作协议。理解这个协议比记住100个API更重要。3.1index.wxml不是HTML的简化版而是“数据驱动的视图声明语言”WXML看起来像HTML但本质完全不同。HTML是“命令式”你告诉浏览器“画一个div里面放个pp里写‘Hello’”。WXML是“声明式”你告诉框架“这里应该显示一个列表列表项来自data里的list数组每项显示name字段”。!-- index.wxml -- view classcontainer text classtitle欢迎来到 {{appName}}/text view wx:for{{list}} wx:keyid classitem text{{index 1}}. {{item.name}}/text text价格¥{{item.price}}/text /view button bindtaphandleAdd添加新商品/button /view三个核心机制数据绑定{{}}只能绑定Page.data或Page.setData设置的数据不能执行函数调用如{{formatDate(time)}}会报错。解决方案在setData前先在JS里计算好格式化后的值再传入。列表渲染wx:forwx:key是性能关键。wx:keyid告诉框架每个列表项的唯一标识是item.id。如果省略框架会用数组下标当key当列表排序、增删时视图更新会错乱。避坑实录某次我忘了写wx:key用户拖拽排序商品结果价格和名称错位查了两小时才发现是key缺失。事件绑定bindtapbindtaphandleAdd表示点击时触发Page对象上的handleAdd方法。注意它不支持内联JS如bindtapadd(1)所有参数必须通过>!-- 正确通过>// index.js Page({ data: { list: [ { id: 1, name: 苹果, price: 5.5 }, { id: 2, name: 香蕉, price: 3.2 } ] }, handleItemClick(e) { const id e.currentTarget.dataset.id; // 获取>/* index.wxss */ .container { padding: 20rpx; background-color: #f5f5f5; } .title { font-size: 32rpx; color: #333; text-align: center; margin: 40rpx 0; } .item { background-color: #fff; margin: 20rpx; padding: 30rpx; border-radius: 12rpx; box-shadow: 0 2rpx 10rpx rgba(0,0,0,0.05); } /* 微信特有page 选择器用于设置整个页面背景 */ page { background-color: #f5f5f5; }关键细节rpxresponsive pixel是微信的响应式单位。规定屏幕宽为750rpx。iPhone 6/7/8是375px宽所以1rpx 0.5pxiPhone 12 Pro Max是428px宽1rpx ≈ 0.566px。优势一套样式适配所有机型。陷阱rpx只对宽度、高度、字体大小等有效border-width、box-shadow的rpx值在部分安卓机上渲染异常。稳妥方案边框、阴影一律用px如border: 1px solid #eee。page选择器是全局的它作用于整个小程序页面的根节点。你可以在app.wxss里写page { background: #f0f0f0; }这样所有页面都有统一背景无需每个页面单独写。!important在WXSS中无效。如果你发现样式没生效不是优先级问题而是选择器没匹配上或style内联样式覆盖了它。调试技巧在开发者工具的“WXML面板”里右键元素→“在WXSS面板中定位”直接跳转到生效的样式行。3.3index.js页面逻辑的“神经中枢”生命周期是操作窗口index.js定义了一个Page对象它不是普通JS对象而是微信框架注入的“页面实例”。它的每个方法都在特定时间点被框架调用错过时机操作就失效。// index.js Page({ // 页面初始数据 data: { appName: 我的小店, list: [], loading: false }, // 页面加载时触发首次进入页面 onLoad(options) { console.log(页面加载, options); // 此处适合获取URL参数、发起首屏数据请求 this.fetchList(); }, // 页面初次渲染完成时触发DOM已挂载可操作节点 onReady() { console.log(页面渲染完成); // 此处适合获取节点信息wx.createSelectorQuery、启动动画 }, // 页面显示/切入前台时触发比onLoad更频繁 onShow() { console.log(页面显示); // 此处适合检查登录态、刷新未读消息数 }, // 页面隐藏/切入后台时触发 onHide() { console.log(页面隐藏); }, // 页面卸载时触发如navigateTo跳转、redirectTo关闭 onUnload() { console.log(页面卸载); }, // 下拉刷新触发 onPullDownRefresh() { this.fetchList().then(() { wx.stopPullDownRefresh(); // 必须手动停止否则下拉动画一直转 }); }, // 上拉触底触发 onReachBottom() { console.log(触底加载); }, // 用户点击右上角菜单...触发 onShareAppMessage() { return { title: 快来看我的小店, path: /pages/index/index }; }, // 自定义方法 fetchList() { this.setData({ loading: true }); return wx.request({ url: getApp().globalData.apiBase /products, success: (res) { if (res.data.code 0) { this.setData({ list: res.data.data, loading: false }); } }, fail: () { this.setData({ loading: false }); } }); }, handleAdd() { // 模拟添加 const newItem { id: Date.now(), name: 新品, price: 99.9 }; this.setData({ list: [...this.data.list, newItem] }); } });生命周期详解onLoadvsonShowonLoad只在页面首次加载时执行一次适合做“一次性初始化”onShow每次页面可见都会执行适合做“状态同步”。比如用户从商品页返回首页首页的onShow会触发你可以在这里检查购物车数量是否变化。onReady是操作DOM的唯一安全时机。你想用wx.createSelectorQuery获取一个view的高度必须在onReady里调用否则查询不到节点。原理onLoad时WXML还没编译成真实节点树onReady时才完成。onPullDownRefresh必须配对wx.stopPullDownRefresh()。这是硬性要求不调用就会卡住下拉动画。经验所有异步操作如request、setTimeout完成后都要确保调用stopPullDownRefresh最好用try/catch包裹。3.4index.json页面级“微宪法”覆盖全局配置index.json是页面专属配置文件它会覆盖app.json里的同名设置。比如app.json里设置了navigationBarTitleText: 我的小程序但在index.json里写{ navigationBarTitleText: 首页, usingComponents: { custom-button: /components/button/button } }那么首页的导航栏标题就会变成“首页”而不是“我的小程序”。更重要的是usingComponents字段它声明了当前页面要用到的自定义组件。自定义组件是小程序工程化的基石。它把重复UI如带图标的按钮、评分星星、地址选择器封装成独立模块一处修改全站生效。// components/button/button.json { component: true, usingComponents: {} }!-- components/button/button.wxml -- button classbtn bindtaphandleTap image src{{icon}} classicon wx:if{{icon}}/image text classtext{{text}}/text /button// components/button/button.js Component({ properties: { text: { type: String, value: 按钮 }, icon: { type: String, value: } }, methods: { handleTap() { this.triggerEvent(click); // 向父页面抛出 click 事件 } } });在index.wxml中使用!-- 引入组件 -- custom-button text立即购买 icon/assets/icons/buy.png bind:clickonBuyClick/custom-button核心价值避免在每个页面重复写相同的按钮样式和逻辑。当设计规范更新如按钮圆角从8rpx改成12rpx你只需改button.wxss所有页面自动更新。4. 真机调试的生死线为什么“开发者工具能跑真机就白屏”这是所有新手必经的“顿悟时刻”。你在开发者工具里点运行页面丝滑流畅一扫码到iPhone上首页一片空白控制台空空如也连console.log都没输出。你怀疑人生重启工具、重装微信、重连WiFi……最后发现问题出在一个你从未注意过的配置上。4.1 白屏的三大元凶与逐级排查链路我整理了过去两年帮学员解决的137例真机白屏案例92%集中在以下三个环节。排查必须按顺序进行跳过前面后面全是徒劳。第一步检查project.config.json中的appid与libVersion现象真机扫码后页面加载圈转几秒直接白屏开发者工具控制台无报错。根因appid填写错误或libVersion高于用户微信版本。验证方法打开微信 → 我 → 设置 → 关于微信 → 版本号确认微信客户端版本如8.0.45查微信官方文档《基础库版本说明》找到该微信版本对应的基础库如8.0.45对应基础库3.4.5对照project.config.json里的libVersion若为3.4.8则高于用户设备支持版本必然白屏。修复方案将libVersion降级至3.4.5重新编译。注意降级后不能使用3.4.5不支持的新API如wx.getBatteryInfo。第二步检查app.json中pages路径的大小写与斜杠现象真机上部分页面能打开部分页面白屏且白屏页面的onLoad生命周期从未触发。根因app.json里写的路径与文件系统实际路径不一致。Windows不敏感iOS/macOS严格区分。验证方法在开发者工具左侧“项目目录”中右键pages/index/index.js→ “在资源管理器中显示”观察资源管理器地址栏路径如显示为D:\myproject\pages\Index\Index.js首字母大写对照app.json里写的pages/index/index全小写二者不匹配。修复方案统一改为小写或重命名文件夹为index。终极技巧在VS Code里安装插件“Auto Rename Tag”它能同步重命名文件和引用避免遗漏。第三步检查sitemap.json是否阻止了首页索引现象真机扫码后首页白屏但点击底部Tab切换到“日志”页却能正常显示。根因sitemap.json里把首页disallow了微信认为该页面不可见拒绝渲染。验证方法打开sitemap.json查找是否有page: pages/index/index且action: disallow的规则或者临时删掉整个sitemap.json重新编译测试。修复方案确保首页在sitemap.json中为action: allow或直接删除sitemap.json微信会默认允许所有页面。注意以上三步排查完若仍白屏请开启开发者工具右上角“详情→本地设置→不校验合法域名”并确保真机与电脑在同一WiFi下。真机调试依赖本地HTTP服务防火墙或路由器隔离会导致连接失败。4.2 网络请求的“双重门禁”开发环境与生产环境的权限切换wx.request是小程序最常用API也是权限最复杂的API。它面临两道门禁门禁层级触发条件检查方式解决方案第一道开发者工具本地校验仅在开发者工具中生效工具右上角“详情→本地设置→不校验合法域名”勾选此项本地调试时可访问任意HTTP/HTTPS域名第二道真机/体验版线上校验所有非本地环境真机、体验版、正式版强制生效微信公众平台“开发管理→开发设置→服务器域名”将你的API域名如https://api.example.com添加到“request合法域名”列表致命误区很多人只配了开发环境忘了配线上环境。结果就是开发者工具里wx.request返回200真机扫码后fail回调里打印{errno: -1, errMsg: request:fail net::ERR_CONNECTION_REFUSED}。实操步骤登录微信公众平台 → 左侧菜单“开发管理” → “开发设置”找到“服务器域名”区域在“request合法域名”输入框中填入你的API域名注意只填域名不带http://或https://不带路径如api.example.com点击“保存”关键一步回到开发者工具点击左上角“编译”按钮右侧的“上传” → 上传为体验版再扫码测试。额外提醒如果你的API是HTTP协议非HTTPS微信只允许在本地调试时使用线上环境体验版/正式版强制要求HTTPS。解决方案要么升级API为HTTPS要么使用微信云开发自带HTTPS域名。4.3 登录态丢失为什么“用户刚授权刷新页面就变游客”小程序没有传统Cookie机制用户登录态靠wx.login获取的code换session_key和openid维持。这个过程极易断链。典型断链场景用户授权登录后页面跳转新页面onLoad时getApp().globalData.userInfo为空用户杀掉小程序进程再重新打开之前登录态消失多页面共享userInfo但某个页面setData时误改了globalData引用。正确登录流程精简版// utils/auth.js function login() { return new Promise((resolve, reject) { wx.login({ success: (res) { // 1. 获取 code const code res.code; // 2. 发送 code 到自己服务器换取 openid/session_key wx.request({ url: getApp().globalData.apiBase /login, method: POST, data: { code }, success: (res) { if (res.data.code 0) { // 3. 将用户信息存入 globalData 和 storage const userInfo res.data.data; getApp().globalData.userInfo userInfo; wx.setStorageSync(userInfo, userInfo); resolve(userInfo); } } }); } }); }); } // pages/index/index.js Page({ onLoad() { // 每次页面加载先检查本地缓存 const cachedUser wx.getStorageSync(userInfo); if (cachedUser) { this.setData({ userInfo: cachedUser }); return; } // 缓存不存在触发登录 login().then(userInfo { this.setData({ userInfo }); }); } });核心原则globalData只作内存缓存必须配合wx.setStorageSync持久化否则进程重启即丢失不要在onLoad里无条件调wx.login它会弹授权框影响用户体验。应先查缓存缓存失效再触发wx.login获取的code有效期极短5分钟且一次只能用一次。服务器换完openid后code即失效。5. 从“能跑”到“能用”五个让小程序真正落地的实战细节做完一个能显示、能跳转、能请求的小程序只是完成了10%。剩下90%是那些让产品真正可用、用户愿意用、老板愿意投钱的细节。这些细节往往藏在文档角落却决定项目成败。5.1 图片加载的“三重保险”策略小程序图片加载失败是用户流失的第一大原因。一张占位图没显示用户就可能划走。我们必须为每张图片准备三重保险。!-- index.wxml -- image src{{product.image}} modeaspectFill binderroronImageError bindloadonImageLoad classproduct-img >// index.js Page({ data: { product: { image: https://example.com/goods/1.jpg } }, // 图片加载成功 onImageLoad(e) { const index e.currentTarget.dataset.index; // 可在此记录加载耗时用于性能监控 }, // 图片加载失败 onImageError(e) { const index e.currentTarget.dataset.index; // 1. 先尝试备用图 const fallbackUrl /assets/images/fallback-product.png; // 2. 更新 data触发重新渲染 const newData {}; newData[product.image] fallbackUrl; this.setData(newData); // 3. 【进阶】记录错误上报监控系统 wx.reportAnalytics(image_load_error, { url: e.detail.errMsg, page: index, timestamp: Date