Taro 多端框架：一套 React 代码，同时出小程序和 H5

有读者问我，做个活动页，微信小程序要、网页也要，是不是得写两套。我说不一定，跨端框架能干这事，京东的 Taro 就是其中一个。他让我先试试再说话，于是我把它拉下来跑了一遍。

结论先说：能跑，小程序和 H5 都编译出来了，代码确实是同一份。但过程里有些地方，官方文档没写。

Taro 能干什么

一句话：一份 React 代码，编译成微信小程序、H5、支付宝小程序、抖音小程序等多个端。

按用途对号入座——

• 一个产品要上好几个端：小程序和网页共用一套业务代码，改一次全端生效
• 团队只有前端会 React：不用为了小程序再去学一套 WXML/WXSS
• 活动页、营销页：一套代码出 H5 发朋友圈、出小程序码扫码
• 已有 React 项目想搬到小程序：组件、状态管理、路由概念基本能平移
• 想同时吃微信和支付宝的流量：多端编译，不用维护两套

它不适合做「只上微信小程序」的项目——那种情况原生写法更省事，Taro 的抽象层反而多一层。

核心功能亮点

• 多端编译：微信、支付宝、抖音、百度小程序，H5，React Native 都支持
• React 语法：JSX、Hooks、函数组件直接写，不用学新框架
• 一套路由：页面路由配置一次，各端自动适配
• 组件库生态：Taro UI、NutUI 这些现成的，小程序组件也能直接用
• 多端样式：px 按 750 设计稿自动换算，各端尺寸不至于跑偏
• 条件编译：个别端要差异代码，用环境变量或者平台判断切
• CLI 工具链：建项目、编译、预览、打包一条龙
• TypeScript 完整支持

源码怎么拿的

GitHub 上 NervJS/taro，37,714 个 Star，主语言 TypeScript。最新 release 是 v4.3.0，2026 年 9 月 29 日发的。

这里先提一句许可证。GitHub 页面把它的 license 标成 Other，我一开始以为又是那种「源码可见但限制商用」的授权，差点跳过。拉下 LICENSE 原文才看清，开头就是标准 MIT，Copyright (c) 2018 O2Team。之所以被识别成 Other，是因为 MIT 正文后面附了一大串第三方代码的声明——react-devtools、vue-devtools 这些。GitHub 的识别器匹配不上就归到 Other 了。所以是可以收的。

下载遇到点小麻烦。直接连 codeload.github.com 走本机代理，报 CONNECT tunnel failed, response 502。换成加速前缀才通——你要是也在国内，去 tag 页拉压缩包大概率会撞上同一个墙。

21 MB，37 秒下完。解压出来 53.7 MB、5,268 个文件。是个 monorepo，packages/ 下面四十多个 @tarojs/* 子包，还有 crates/ 放 Rust 代码。

卡住的地方：taro init 不吃管道输入

装 CLI 很快，npm install @tarojs/cli@4.3.0，482 个包，两分半。

然后 taro init。它的 --help 里列了 --name、--typescript、--css、--framework、--compiler、--template、--platforms，看着挺全，我就想全参数跑一遍。

结果它还是弹了个框：

? 请选择需要支持的平台？ (Press <space> to select ...)
>(*) 微信小程序
 ...
 (*) H5

翻 dist/cli.js 才明白，--platforms 虽然写在帮助里，但 init 命令的参数映射压根没把它传进去。也就是说这个框一定会弹。inquirer 的选择框要有真实终端，我用管道喂回车、喂空格，都没用，进程就那么挂着。

绕法是不走 CLI，直接调它底层的 @tarojs/binding.createProject。里面两个参数得注意，都是 Rust 那边的枚举，大小写敏感，报错还只有一句：

Error: value `"npm"` does not match any variant of enum `NpmType`
Error: Missing field `period`

npm 要写成 'Npm'，另外 period 必须传 'CreateAPP'——这个字段文档里根本没有，我是翻 binding.d.ts 才看到的。

生成出来 24 个文件，React 18 + TS 5 + Sass + Webpack5。依赖 1,502 个包，四分钟出头装完，node_modules 287 MB。

界面改成了「源码湾」

老规矩，能改显示名的地方都改了。src/index.html 的标题改成「源码湾 · Taro 多端演示」，app.config.ts 里导航栏标题改「源码湾演示」、底色换成藏蓝，另外重写了首页和关于页——原模板只有一个 Hello world，拿来做截图实在没什么可看的。

首页放了品牌 logo、一句口号、技术栈卡、一个计数器按钮，还有一排「可以编译到这些端」的标签；关于页列了各包的版本号和一句品牌说明。logo 准备了深色和白色两版，深蓝底上用白色那版，否则藏蓝图标贴在藏蓝背景上等于隐形。

Taro 本体的名字我一个没动。框架改名不是品牌化，是自毁——@tarojs/* 的包名、官方文档、社区示例全对不上，用户搜都搜不到。这点我写在成品说明里了，没藏着。

小程序端倒是自动跟着改了：app.json 和页面的 .json 里 navigationBarTitleText 都是「源码湾演示」。

真跑起来的数据

H5 生产构建 13.2 秒，入口 bundle 282 KiB。超过 webpack 建议的 244 KiB，会出一条 EntrypointsOverSizeLimitWarning，不影响运行。

微信小程序构建 5.79 秒，产物 24 个文件、232 KB，app.json、app.wxss、base.wxml、两个页面的 .js/.json/.wxml/.wxss 都在。index.wxml 打开只有两行，走 base.wxml 的动态模板——这是 Taro 3 以后的标准做法，不是编译失败，我第一次看到也愣了一下。

开发服务器 npm run dev:h5 起在 10086 端口，curl 返回 200，改文件后能看到热更新产物生成。

要说明一点：小程序端我只验到「编译成功 + 产物结构完整 + 配置正确」，没在微信开发者工具里真机跑过，本机没装那个工具。所以成品里的「构建产物/小程序端」目录，你导入工具后能不能一次点亮，我不敢打包票，只能说编译这一关是干净的。

几个会让你怀疑人生的细节

宽屏下整页会被放大。 designWidth: 750 的意思是，你写 320px 实际等于 320/750 × 视口宽度。在 1280 的浏览器里，那个 320px 的 logo 变成 546px 宽，整页像被放大镜罩住了。这是默认行为不是 bug，但第一次见到会以为样式崩了。要么给容器加 max-width，要么按端改 designWidth。

page 这个选择器在 H5 端不生效。 我在 app.scss 里写了 page { background: #f3f7fa }，小程序端正常，H5 端底部一片纯白。因为 H5 里根本没有 page 这个节点。得写到自己的页面根 class 上。

Image 组件默认占 300×225 的盒子。 只给 width 配 mode="widthFix"，图片还没加载完就撑出 225px 高的空白，首屏那块 hero 一下变成 440px 高，看着像布局炸了。显式给宽高、改用 aspectFit 才对。

Button 在 H5 有固定宽度 184px。 我把 padding 调小之后，「归零」两个字只剩一个「归」露在外面。加 width: auto 解决。

缺点，该说的都说

一，重。1,502 个依赖，node_modules 287 MB，就算用国内镜像源，装一次也要四分半。你要是只想做个小程序，微信原生开发不用等这么久。

二，H5 首屏 282 KiB 起。跨端是有代价的，运行时、组件库都得打进去。To C 的页面要抠首屏性能，这个数不太好看。

三，官方模板太素。就一个 Hello world 页面，靠它学不会 Taro。真正要看的是官方文档和 examples，那些得自己翻。

四，小程序端离不开微信开发者工具。没装工具，你连产物长什么样都验证不了，等于摸黑。

五，4.x 和 3.x 的配置写法有差异。网上能搜到的教程一大半是 3.x 的，照抄经常报错，得对版本号。

六，npm 上的 tag 太多。latest、beta、alpha、canary、v3-latest、theta、nightly 一堆，随手 npm i @tarojs/cli 万一碰上 next 分支的旧版本，能折腾你半天。

七，taro init 那套交互对自动化极不友好。想写脚本批量生成项目，就得自己去摸底层 API，文档里没有。

适合谁

手上有现成 React 团队、要同时出小程序和 H5 的，值得试。它的写法跟 React 基本一致，View/Text 换掉 div/span，剩下的 hooks、状态、组件拆分都照旧。

只是做个纯网页，或者只做一个小程序，那还是别绕这一圈。

怎么拿

源码、能直接跑的演示项目（node_modules 已经装好了，不用再联网装依赖）、两端的构建产物，都打在一个包里。

自己从官方拉也行，就是环境、依赖、配置、目录结构得自己理一遍。包里是跑通之后才打的——要省这几步，直接拿下面这个。

用不惯网盘也可以发邮件给我，地址在站底。

两个小提醒：

1. 建议先「转存到自己网盘」再下载——直接下载的链接容易失效，转存后就是你自己的了，随时能下；
2. 手机上操作：点开链接 → 右下角「保存到网盘」→ 回夸克 App 的「我的网盘」里下载。

自己动手的成本：装 CLI 482 个包、两分半，taro init 才是第一道坎——--platforms 明明写在 --help 里，代码里压根没接到参数上，选择框一定会弹，管道喂回车喂空格都没用，进程就那么挂着。绕法是跳过 CLI 直接调 @tarojs/binding.createProject，两个 Rust 枚举参数大小写敏感：npm 要写成 Npm，period 必须传 CreateAPP（字段文档里没有，只能翻 binding.d.ts）。生成完还要装 1,502 个包、node_modules 287 MB、四分钟出头。这些我都趟过一遍才做出能跑的演示站，包里是现成的工程，装完依赖直接 npm run dev:h5。

装之前先确认两件事：Node 18 以上（我用 22 跑的）、微信开发者工具（要预览小程序必须装，光编译不够）。H5 那边不需要额外环境，起个静态服务器就能看。

最后提醒一句：Taro 是 MIT，我改的只有演示页面的品牌，框架本身没动。你要拿去商用，还是自己看一眼 LICENSE，别听我一句就当真。