uni-app 字节跳动小程序开发 uni-app如何编译成抖音小程序

uni-app 编译抖音小程序必须使用 uni-app@3.99.0+ 和 @dcloudio/uni-platform-toutiao 插件，手动注册插件、配置 manifest.json 和 pages.json，并适配 tt.xxx 原生 API 及真机调试限制。

uni-app 编译抖音小程序前必须装对 CLI 和插件

uni-app 官方不直接支持字节跳动小程序（即抖音小程序），所谓“编译成抖音小程序”，实际是通过 @dcloudio/uni-cli + @dcloudio/uni-platform-toutiao 插件实现的。很多人卡在第一步：npm run build:mp-toutiao 报错 command "build:mp-toutiao" not found，本质是插件没装或版本不匹配。

• 必须用 uni-app@3.99.0+（v4 早期 alpha 版本已弃用该平台支持）；v3.99.x 是目前唯一稳定支持抖音小程序的主线
• 安装命令是：npm install @dcloudio/uni-platform-toutiao@latest --save-dev，不是 uni-app-plus 或其他平台插件
• 插件安装后需手动在 vue.config.js 或 vue.config.ts 中注册（若项目有该配置文件）：

  module.exports = {configureWebpack: {     plugins: [       require('@dcloudio/uni-platform-toutiao')()]   } }

• 不配插件、不升级 CLI、或用了 v4 的 uni-app 包，都会导致编译命令不存在或生成空目录

build:mp-toutiao 输出目录结构不符合字节开发者工具要求

抖音小程序开发者工具只认标准的 project.config.json + app.js/app.json 结构，而 uni-app 默认输出到 dist/build/mp-toutiao，但该目录里没有 project.config.json，且 app.json 字段名和抖音规范不完全一致（比如 tabBar 的 iconPath 必须是相对路径，不能带 /static/ 前缀）。

• 必须在 manifest.json 的“字节跳动小程序设置”里填好 appid，否则 app.json 里 app_id 为空，开发者工具拒绝打开
• static 下的图标资源要挪到 src/static，并在 pages.json 中用 ./static/xxx.png 写法，否则编译后路径解析失败
• 抖音小程序不支持 subNVue 和 renderjs，相关代码需用条件编译包裹：// #ifdef MP-TOUTIAO …… // #endif
• 输出后建议用开发者工具「导入项目」时，直接选 dist/build/mp-toutiao 目录，不要套一层父文件夹

抖音小程序特有 API 需桥接调用，uni.getSystemInfoSync() 返回字段不全

uni-app 的 uni.xxx API 在抖音端是靠 @dcloudio/uni-platform-toutiao 映射到 tt.xxx 实现的，但映射不全。比如 uni.getSystemInfoSync() 返回对象里没有 system（如“Android 13”）、model（手机型号），只有 platform、version 等基础字段——这是因为抖音小程序原生 API tt.getSystemInfoSync() 本身就不返回这些。

• 涉及设备信息、用户授权、广告、音视频等能力，优先查抖音官方文档 tt.xxx 接口，再看 uni 封装是否覆盖；没覆盖就直接用 tt.xxx（需加运行期判断：if (typeof tt !== 'undefined')）
• uni.login() 在抖音端实际调的是 tt.login()，但返回的 code 是抖音侧 code，不是微信的，后端需对接字节开放平台换取 open_id
• 自定义组件中使用 tt.createVideoContext 等原生上下文，不能依赖 uni.createVideoContext，后者在抖音端未实现
• 所有 tt. 调用必须加 try/catch，抖音小程序某些低端机型或旧版本会直接抛 tt is not defined

真机调试时白屏、onLaunch 不触发、setData 报错

抖音开发者工具模拟器基本可用，但真机预览常白屏，常见原因是资源加载失败或生命周期钩子执行异常。抖音小程序对 JS 错误更敏感，一个未捕获的 Promise reject 就会导致整个页面挂起，且控制台不报错。

• 检查 networkTimeout 是否过短：在 manifest.json → 字节跳动小程序设置 → 网络超时 里设为 30000（默认 6000，容易触发请求中断）
• onLaunch 在抖音端可能被延迟触发，尤其冷启动时；不要在其中同步依赖未就绪的 tt.getSystemInfo 结果，改用回调或 Promise
• this.setData 报 Cannot read property 'setData' of undefined，多因组件内 this 指向丢失，需确保方法绑定正确（如 @click="handleClick.bind(this)" 或箭头函数）
• 真机调试务必开启“远程调试”，并在抖音 App 内打开“开发者选项 → 启用调试”，否则连不上 devtools

抖音小程序的编译链路比微信更脆弱，插件、CLI、平台配置三者版本稍有不匹配，就会静默失败。最常被忽略的是：你以为跑通了 build:mp-toutiao，其实只是生成了空目录，或者 app.json 格式不合法导致开发者工具压根没加载逻辑层。