必须在manifest.json中正确配置mp-weixin.appid等完整字段，否则HBuilderX发行时将静默生成无效包；需通过「发行→小程序-微信」生成unpackage/dist/build/mp-weixin目录产物并确保project.config.json等文件齐全。
必须先在 manifest.json 里填对 mp-weixin.appid，否则所有后续操作都会失败——不是报错，而是静默生成无效包。
manifest.json 中微信小程序配置项必须写全
很多人只改了 appid 就以为完事，但微信小程序构建依赖完整的 mp-weixin 配置块。缺字段会导致 HBuilderX 打包时跳过某些编译步骤，最终在开发者工具里白屏或样式错乱。
-
appid必须是微信公众平台「开发管理 → 开发设置」里看到的正式 AppID（带wx前缀），不能是测试号 ID 或空字符串 -
setting.urlCheck建议设为false，否则上线前需额外配置服务器域名白名单，本地调试阶段容易卡住 -
usingComponents必须为true，否则自定义组件无法被识别（尤其用了uni_modules里的插件时） -
permission段可选，但如果用到uni.getLocation等 API，不声明scope.userLocation描述，真机上会直接拒绝授权
正确示例：
{
"name": "我的小程序",
"appid": "",
"description": "",
"versionName": "1.0.0",
"versionCode": "100",
"transformPx": false,
"app-plus": { /* ... */ },
"mp-weixin": {
"appid": "wx1234567890abcdef",
"setting": {
"urlCheck": false,
"es6": true,
"postcss": true,
"minified": true
},
"usingComponents": true,
"permission": {
"scope.userLocation": {
"desc": "用于展示附近门店"
}
}
}
}HBuilderX 发行时必须选“小程序-微信”，不能点“运行”
「运行 → 运行到小程序模拟器」只是启动微信开发者工具并加载临时代码，它不走完整构建流程，不会处理条件编译、资源压缩、分包优化等关键步骤。真正发布必须用「发行」菜单。
微信小程序 TabBar 图标生成
下载
微信小程序 TabBar 图标生成技能，使用 Python PIL 绘制简约几何图标（未选中灰、选中绿），自动写入 app.json 配置。适用于“生成 tabBar 图标”、“底部菜单栏图标”、“tab 图标”等指令。
- 点击顶部菜单「发行 → 小程序-微信」，不是「运行」
- 首次发行前，确保微信开发者工具已登录且处于关闭状态（否则 HBuilderX 可能连不上端口，报错
IDEmay already started at port xxxx） - 发行成功后，HBuilderX 会在控制台输出路径：
unpackage/dist/build/mp-weixin，这个目录才是可上传的完整小程序工程 - 不要手动复制
dist/dev/mp-weixin——那是开发模式产物，含未转义的 Vue 模板和调试代码，上传后必报错
上传前必须检查 unpackage/dist/build/mp-weixin 目录结构
微信开发者工具要求根目录下存在 project.config.json 和 app.js，而 uni-app 默认不生成 project.config.json。如果缺失，开发者工具会提示「不是合法的小程序项目」。
- 发行完成后，打开
unpackage/dist/build/mp-weixin，确认有以下文件：app.js、app.json、app.wxss、project.config.json（若无，需手动创建） -
project.config.json最小可用内容只需两行：{ "description": "project configuration file", "setting": { "urlCheck": false } } - 检查
app.json中usingComponents是否为true，若为false，说明manifest.json配置未生效，需回退检查 - 如果有分包，在
subNVue或subNVue目录下发现空文件夹？那是 HBuilderX 的遗留 bug，删掉整个subNVue文件夹再重新发行
上传后真机白屏或接口 404 的根本原因
不是代码写错了，大概率是环境链路断在三个地方之一：域名、HTTPS、条件编译。
- 所有网络请求必须走
https，且域名必须在微信公众平台「开发管理 → 开发设置 → 服务器域名」中提前备案（包括request、uploadFile、downloadFile对应的域名） - 使用
uni.request时，不要写http://，哪怕本地调试也得配代理或改用https://；否则上传后直接被微信拦截，控制台无报错，只返回空响应 - 涉及微信特有 API（如
wx.login、wx.chooseAddress）的逻辑，务必用#ifdef MP-WEIXIN包裹，否则 H5 或 App 端运行时会报undefined is not a function - 图片路径别用绝对
/static/xxx.png，优先用相对路径或@/static/xxx.png，否则分包后路径解析失败
最常被忽略的是：发行后没关掉 HBuilderX 的「热更新」开关，导致开发者工具里看到的是旧 JS 文件。每次发行前，建议清空 unpackage 目录再操作。另外，微信开发者工具右上角「详情 → 本地设置」里勾选「不校验合法域名」仅对调试有效，上传时完全不生效。
