NutUI

京东风格的轻量级移动端组件库，支持 Vue / React 双技术栈，基于 Taro 实现一套代码同时运行于 H5 与多端小程序。

技术简介说明

NutUI 是由京东零售前端团队（jdf2e）开发并开源的移动端 UI 组件库，设计语言源自京东 APP 10.0 视觉规范。它同时提供 Vue 3 和 React 两套实现，并与京东跨端框架 Taro 深度整合，使开发者可以用一套代码同时产出 H5 页面和微信、支付宝、百度、字节跳动、QQ、飞书、快手等多端小程序。

NutUI 自 2018 年发布至今已经历四个大版本迭代，当前主版本为 4.x（Vue）和 3.x / 4.x beta（React），提供 80+ 高质量组件，覆盖电商、物流、金融等移动端主流业务场景。

基本信息

快速上手

安装

# Vue 3 H5 版本
npm install @nutui/nutui
 
# Vue 3 Taro 多端版本
npm install @nutui/nutui-taro
 
# React H5 版本
npm install @nutui/nutui-react
 
# React Taro 多端版本
npm install @nutui/nutui-react-taro
 
# 图标包（Vue）
npm install @nutui/icons-vue        # H5
npm install @nutui/icons-vue-taro   # Taro 小程序

基础配置（Vue 3 + Taro 为例）

# 1. 使用 Taro 脚手架初始化项目
taro init myApp
# 选择 Vue 3 + NutUI 模板
 
# 2. 安装 HTML 插件
npm install @tarojs/plugin-html

// config/index.js
{
  plugins: ['@tarojs/plugin-html'],
  designWidth: 375,
  sass: {
    data: '@import "@nutui/nutui-taro/dist/styles/variables.scss";'
  }
}

最小示例

方式一：全局注册

// main.ts
import { createApp } from 'vue'
import NutUI from '@nutui/nutui-taro'
import '@nutui/nutui-taro/dist/style.css'
import App from './App.vue'
 
createApp(App).use(NutUI).mount('#app')

<!-- 使用组件 -->
<template>
  <nut-button type="primary" @click="handleClick">主要按钮</nut-button>
  <nut-cell title="单元格" desc="描述文字"></nut-cell>
</template>

方式二：自动按需引入（推荐）

npm install -D unplugin-vue-components @nutui/auto-import-resolver

// vite.config.ts / config/vite.ts
import Components from 'unplugin-vue-components/vite'
import NutUIResolver from '@nutui/auto-import-resolver'
 
export default {
  plugins: [
    Components({
      resolvers: [NutUIResolver({ taro: true })]
    })
  ]
}

配置后可直接在模板中使用 <nut-button> 等组件，无需手动 import。

核心概念与架构

多版本架构

NutUI 采用 多包分治 架构，针对不同技术栈和运行环境提供独立包：

NutUI 生态
├── @nutui/nutui              # Vue 3 H5 版本
├── @nutui/nutui-taro         # Vue 3 Taro 多端版本（H5 + 小程序）
├── @nutui/nutui-react        # React H5 版本
├── @nutui/nutui-react-taro   # React Taro 多端版本
├── @nutui/icons-vue          # Vue 图标包（H5）
├── @nutui/icons-vue-taro     # Vue 图标包（Taro）
├── @nutui/auto-import-resolver  # 自动导入解析器
├── @nutui/nutui-bingo        # 大促业务组件
├── @nutui/nutui-cat          # 大促业务组件库
└── @nutui/playground         # 在线 Playground

构建工具链

Taro 整合架构

源代码（Vue/React + NutUI 组件）
        │
        ▼
   Taro 编译层
        │
        ├── H5（Web）
        ├── 微信小程序
        ├── 支付宝小程序
        ├── 百度小程序
        ├── 字节跳动小程序
        ├── QQ 小程序
        ├── 飞书小程序
        └── 快手小程序

NutUI 组件在 Taro 编译过程中自动适配各端语法和样式差异，开发者无需手动处理跨端兼容问题。

核心特性

1. 丰富的组件覆盖

提供 80+ 高质量组件，覆盖基础、布局、导航、数据录入、数据展示、反馈、业务等分类，满足移动端主流场景需求。代表性组件包括：

• 基础组件：Button、Icon、Cell、ConfigProvider
• 导航组件：Navbar、Tabbar、Tabs、Elevator、FixedNav
• 数据录入：Form、Input、Picker、DatePicker、Uploader、Calendar
• 数据展示：Swiper、Table、Tag、Badge、Watermark
• 反馈组件：Dialog、Toast、Notify、ActionSheet、PullRefresh
• 业务组件：Price、GoodsCard、Address、Barrage、Tour

2. CSS Variables 动态主题

4.0 引入 CSS Variables 动态主题能力，通过 ConfigProvider 组件可在运行时动态切换主题，支持：

• 组件级别主题定制
• 暗黑模式（theme="dark"）
• 内置 700+ 个样式变量
• 在线主题定制工具（https://nutui.jd.com/theme/）

<template>
  <nut-config-provider :theme-vars="themeVars">
    <nut-button type="primary">自定义主题按钮</nut-button>
  </nut-config-provider>
</template>
 
<script setup>
const themeVars = {
  '--nut-button-primary-background-color': '#e93b3d',
  '--nut-button-primary-border-color': '#e93b3d'
}
</script>

3. 一套代码多端运行

基于 Taro 跨端框架，一套代码可同时编译到 H5 和微信、支付宝、百度、字节跳动、QQ、飞书、快手等多端小程序，大幅降低多端维护成本。

4. 按需引入与轻量化

• 支持 unplugin-vue-components 自动按需引入，无需手动配置
• 4.0 安装体积减少 42%（14MB → 8MB），包体积减少 39%（3.81MB → 2.3MB）
• 独立图标包减少 595kB 安装体积，移除 125 个字体图标文件节省 464kB
• 主 ES 文件从 624kB 缩减至 11.9kB

5. TypeScript 全面支持

使用 TypeScript 编写，提供完整的类型定义，支持组件 Props、Events、Slots 的类型推导，提升开发体验和代码安全性。

6. 国际化（i18n）

内置国际化支持，已支持英语、印尼语、繁体中文等多语言，国际化资源支持按需引入。

7. 京东设计语言

基于京东 APP 10.0 视觉规范设计，组件风格统一，适合电商、零售、物流等业务场景，同时支持通过主题定制适配自有品牌风格。

8. 高测试覆盖率

单元测试覆盖率超过 80%，保障组件质量和版本迭代稳定性。

9. 服务端渲染支持

提供 SSR（服务端渲染）能力（测试阶段），有助于首屏加载性能和 SEO 优化。

10. 在线 Playground

提供在线代码沙箱（https://nutui.jd.com/playground/），支持在线编写、预览和调试组件代码。

生态图

                    ┌─────────────────────────────────────┐
                    │            NutUI 生态               │
                    └─────────────────┬───────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         │                            │                            │
    ┌────▼────┐                 ┌─────▼─────┐               ┌─────▼─────┐
    │  Vue 版  │                 │  React 版  │               │  工具链   │
    └────┬────┘                 └─────┬─────┘               └─────┬─────┘
         │                            │                            │
    ┌────┴────┐                  ┌────┴────┐                ┌─────┴─────┐
    │nutui    │                  │nutui-   │                │icons-vue  │
    │(H5)     │                  │react    │                │(图标包)    │
    ├─────────┤                  │(H5)     │                ├───────────┤
    │nutui-   │                  ├─────────┤                │auto-import│
    │taro     │                  │nutui-   │                │-resolver  │
    │(多端)    │                  │react-   │                ├───────────┤
    └─────────┘                  │taro     │                │playground │
                                 │(多端)    │                │(在线沙箱)  │
                                 └─────────┘                └───────────┘
         │                            │
    ┌────▼────────────────────────────▼────┐
    │            Taro 跨端框架              │
    │   H5 / 微信 / 支付宝 / 百度 / 字节    │
    │   QQ / 飞书 / 快手 / 鸿蒙            │
    └──────────────────────────────────────┘
         │
    ┌────▼────────────────┐
    │    社区生态          │
    │  nutui-uniapp       │  ← 基于 4.x 的 uni-app 适配
    │  uni-nutui          │  ← 基于 3.x 的 uni-app 适配
    └─────────────────────┘

官方包一览

社区生态

适用场景

1. 京东风格电商应用

组件设计源自京东 APP 视觉规范，内置 Price、GoodsCard、Address、Barrage 等电商专属组件，天然适合电商、零售、物流类移动端应用。

2. Taro 跨端小程序项目

与 Taro 深度整合，是 Taro 官方推荐的 Vue 组件库。一套代码同时输出 H5 和微信、支付宝、字节跳动等多端小程序，适合需要多端覆盖的业务。

3. 多品牌 / 多主题应用

内置 700+ CSS 变量和 ConfigProvider 组件，支持运行时动态切换主题和暗黑模式，适合需要支持多品牌皮肤或深浅色模式的应用。

4. Vue 3 + TypeScript 技术栈项目

完全使用 TypeScript 编写，类型定义完整，适合对类型安全要求较高的中大型项目。

5. 需要快速搭建移动端原型

80+ 组件覆盖主流场景，配合在线 Playground 和自动按需引入，可快速搭建移动端 MVP 或原型。

6. 京东内部及上下游业务

京东内部广泛使用，与京东设计体系一脉相承，适合京东生态链企业或外包团队保持视觉一致性。

7. 自定义业务风格组件库

支持通过 SCSS 变量、CSS Variables、ConfigProvider 三种方式定制主题，可基于 NutUI 快速搭建企业自有风格的业务组件库。

开发与工程化

目录结构（Vue 版）

nutui/
├── src/
│   ├── packages/          # 组件源码（每个组件一个目录）
│   │   ├── button/
│   │   ├── cell/
│   │   ├── dialog/
│   │   └── ...
│   ├── styles/            # 全局样式 & 变量
│   └── locales/           # 国际化资源
├── packages/              # 构建产物
├── site/                  # 文档站点
└── vite.config.ts         # 构建配置

开发环境搭建

# 克隆仓库
git clone https://github.com/jd-opensource/nutui.git
 
# 安装依赖
pnpm install
 
# 启动文档站点开发服务器
pnpm run site
 
# 运行单元测试
pnpm run test
 
# 构建
pnpm run build

自定义主题工程化

NutUI 支持三种主题定制方式：

CI / CD 集成

• 使用 Vite 4 构建，兼容主流 CI 平台
• 支持 Tree-shaking，配合打包分析工具可进一步优化
• 提供 @nutui/auto-import-resolver 与 unplugin-vue-components 集成

性能与安全

性能优化

安全考量

• MIT 开源许可：无商业使用限制
• 京东内部实战验证：经过京东 APP 及多个业务线大规模生产验证
• 依赖审计：建议定期使用 npm audit / pnpm audit 检查依赖安全
• SSR 支持：提供服务端渲染能力（测试阶段），有助于安全的数据隔离
• XSS 防护：组件内部对用户输入做了基本的转义处理（具体需参考各组件文档）
• 依赖最小化：4.0 大幅精简了内置依赖（如 Popover 完全无外部依赖）

技术对比

移动端组件库横向对比

选型决策矩阵

最佳实践

1. 优先使用自动按需引入

// 推荐：unplugin-vue-components + @nutui/auto-import-resolver
import Components from 'unplugin-vue-components/vite'
import NutUIResolver from '@nutui/auto-import-resolver'
 
export default {
  plugins: [
    Components({
      resolvers: [NutUIResolver({ taro: true })]
    })
  ]
}

避免全量引入导致包体积膨胀，自动按需引入在编译时只打包使用到的组件和样式。

2. 使用 ConfigProvider 管理主题

<template>
  <nut-config-provider :theme="isDark ? 'dark' : 'light'" :theme-vars="customVars">
    <App />
  </nut-config-provider>
</template>

通过 ConfigProvider 统一管理全局主题和暗黑模式，避免在多处散落样式覆盖代码。

3. Taro 项目注意设计稿宽度

NutUI 默认设计稿宽度为 375px，在 Taro 项目中需确保 designWidth 配置一致：

// config/index.js
module.exports = {
  designWidth: 375
}

如果业务设计稿为 750px，需调整 deviceRatio 配置。

4. Form 组件配合使用

NutUI 的 Form 组件提供了完整的表单校验能力，建议配合 Input、Picker、Uploader 等录入组件统一使用：

<nut-form>
  <nut-form-item label="用户名" required>
    <nut-input v-model="formData.name" placeholder="请输入用户名" />
  </nut-form-item>
</nut-form>

5. 小程序端注意事项

• 小程序端使用 @nutui/nutui-taro 而非 @nutui/nutui
• 部分依赖浏览器 API 的组件在小程序端行为可能不同，需参考文档中的多端兼容说明
• TypeScript 类型提示需将自动生成的 components.d.ts 加入 tsconfig.json 的 include 中

6. 图标按需引入

// 只引入使用到的图标，避免全量加载
import { Check, Close, ArrowDown } from '@nutui/icons-vue'

4.0 起图标独立为单独的包，按需引入可显著减少包体积。

技术局限与边界

1. 社区生态相对有限

npm 周下载量约 5,000、GitHub Star 6.5k，与 Vant（23k+ Star、10 万+ 周下载量）相比差距明显。遇到问题时可参考的社区资源和第三方解决方案较少。

2. 组件 API 丰富度不足

根据第三方对比分析，NutUI 平均每个组件暴露的 API 数量少于 Vant 和 Ant Design Mobile，部分复杂场景下可能需要额外的自定义开发。

3. 非 Taro 小程序不直接支持

NutUI 的小端支持完全依赖 Taro 编译。如果项目使用 uni-app，需要依赖社区维护的 nutui-uniapp 适配层，非官方直接维护，更新可能存在滞后。

4. React 版成熟度低于 Vue 版

React 版（@nutui/nutui-react）起步较晚，当前最新为 v4.0.0-beta，组件数量和文档完善度不及 Vue 版。

5. 文档示例不够详尽

部分组件的代码示例缺少详细的文字说明， Demo 展示偶有多示例混合的情况，新手上手门槛略高于 Vant。

6. 非电商场景优势不明显

虽然支持主题定制，但 NutUI 的设计语言深度绑定京东风格，在非电商场景（如社交、工具、内容平台）中，可能需要较多定制工作。

7. SSR 支持尚在测试阶段

服务端渲染能力仍处于测试阶段，生产环境使用需额外验证和风险评估。

8. 部分 4.0 破坏性变更需注意

升级 3.x → 4.0 时，超过 20 个组件存在结构变更：

• ShortPassword 不再依赖原生键盘
• InfiniteLoading 移除了下拉刷新功能
• Picker 移除了内置弹出层
• 部分组件 kebab-case 命名调整

学习资源

官方资源

技术文章

社区生态

2026 年现状

版本进展

• Vue 版：稳定在 4.3.x 分支，最新 beta 为 4.3.15-beta.1（2026-04），保持活跃迭代
• React 版：正在推进 v4.0.0 大版本，最新 beta 为 v4.0.0-beta.4（2026-06-18），主要适配站点 v16 版本和组件重构
• Taro React 版：稳定在 v3.0.21（2026-05）

维护状态

项目保持活跃维护，京东零售前端团队持续投入。2026 年上半年保持每月 1-2 次的发布节奏，React v4 大版本正在积极开发中。

生态发展

• Taro 深度绑定：作为 Taro 官方推荐的 Vue 组件库地位不变，跨端能力是核心竞争力
• uni-app 社区适配：nutui-uniapp 社区项目基于 4.x 持续更新，扩展了 NutUI 在 uni-app 生态的覆盖
• 组件库竞争格局：在移动端组件库市场中，NutUI 的差异化优势在于 Taro 跨端支持和电商场景组件，但在社区规模、下载量和通用性方面仍落后于 Vant

选型建议（2026）

总结：NutUI 的核心竞争力在于 Taro 跨端能力 和 京东电商设计语言。如果你的项目使用 Taro 开发多端小程序，或需要京东风格的电商组件，NutUI 是当前最成熟的选择。但在纯 H5 场景和社区生态规模上，与 Vant 等头部组件库仍有差距。2026 年 React v4 大版本的推进值得持续关注。