Naive UI 入门实战：安装、全局注册与按需引入完整指南

• 前端
• UI组件

本指南以 naive-ui 仓库中 build/loaders/test/test.md 的 "Get Started" 文档为核心骨架，系统讲解从零接入 Naive UI 的标准流程：npm 安装、在入口文件中全局注册插件、以及面向生产构建的按需引入与 Tree Shaking 方案。读完本文，你将掌握 Naive UI 的最小可运行接入方式、其install插件的底层注册机制（src/create.ts），并了解 Vue 3 下完整可用、主题可定制、TypeScript 友好的工程化用法。

一、环境前提：Naive UI 仅支持 Vue 3

在动手安装之前，先明确版本边界。官方安装文档（demo/pages/docs/installation/enUS/index.md）明确指出：naive-ui 只支持 Vue 3。如果你正在使用 Vue 2 项目，需要另寻其他组件库。

这一点在仓库的工程声明中同样可以验证：

• package.json 的peerDependencies声明为"vue": "^3.0.0"，即安装时要求宿主项目提供 Vue 3 运行时；
• engines字段要求node >= 20，这是仓库当前版本（v2.45.2）的开发与构建基线；
• 项目描述为 "A Vue 3 Component Library. Fairly Complete. Theme Customizable. Uses TypeScript. Fast"（package.json）。

仓库的源码全部使用 TypeScript 编写，入口 src/index.ts 汇出了组件、组合式 API（composables）、create工厂、主题系统（darkTheme/lightTheme/createTheme）、多语言（locales）等全部公共 API。这也是后文"按需引入"可以逐模块import的前提。

二、安装：一条命令引入 naive-ui

原文档的第一步是安装：

npm install --save-dev naive-ui

需要说明的是，--save-dev并非必需。若使用 npm 的默认行为，直接执行官方推荐命令即可：

npm i naive-ui

安装完成后，你可以在package.json的dependencies中看到naive-ui及其版本号（当前仓库版本为 2.45.2）。仓库本身使用 pnpm 管理依赖（packageManager: pnpm@11.10.0），因此如果你的项目同样使用 pnpm，也可以：

pnpm add naive-ui

可选配套：字体与图标

为了让界面呈现与文档一致的效果，官方还推荐两个配套依赖：

• 字体：npm i vfonts（naive-ui 默认字体方案）；
• 图标：推荐使用 xicons 图标库（如@vicons/ionicons5、@vicons/fluent），仓库 demo 中即大量使用@vicons/fluent的图标（见 demo/pages/docs/installation/enUS/index.md 的组件示例）。

这两个是可选依赖，不影响 Naive UI 本身运行。

三、全局注册：入口文件的经典三行接入

原文档给出的最小使用方式是在入口 JS 文件中加入三行代码：

import naive from 'naive-ui' import 'naive-ui/dist/lib/index.css' Vue.use(naive)

其中：

• import naive from 'naive-ui'导入默认导出对象——它同时是一个"插件"，带有install方法；
• import 'naive-ui/dist/lib/index.css'引入组件库的全局样式；
• Vue.use(naive)触发 Vue 插件的install，将全部组件注册为全局组件。

3.1 Vue 3 语法提醒

Vue.use(naive)是 Vue 2 时代的插件挂载写法。在 Vue 3 中，全局插件的挂载统一使用app.use，因此入口文件的实际写法通常是：

import { createApp } from 'vue' import naive from 'naive-ui' import 'naive-ui/dist/lib/index.css' const app = createApp(App) app.use(naive) app.mount('#app')

在<script setup>的 SFC 中，全局注册后的组件可以直接以模板形式使用，无需手动import与components声明，例如<n-button>、<n-input>。

3.2 底层机制：install 到底注册了什么

从源码看，import naive from 'naive-ui'的默认导出定义在 src/preset.ts：

import * as components from './components' import create from './create' const naive = create({ components: Object.keys(components).map( key => components[key as keyof typeof components] ) }) export default naive export const install = naive.install

它把 src/components.ts 中汇出的全部组件收集起来，交给create工厂生成一个插件实例。create的实现位于 src/create.ts，关键逻辑如下：

function create({ componentPrefix = 'N', components = [] }: NUiCreateOptions = {}): NUiInstance { const installTargets: App[] = [] function registerComponent(app, name, component) { const registered = app.component(componentPrefix + name) if (!registered) { app.component(componentPrefix + name, component) } } function install(app: App): void { if (installTargets.includes(app)) return installTargets.push(app) components.forEach((component) => { const { name, alias } = component registerComponent(app, name, component) if (alias) { alias.forEach((aliasName) => registerComponent(app, aliasName, component)) } }) } return { version, componentPrefix, install } }

从中可以读出三条重要事实：

1. 注册规则：所有组件默认以N为前缀注册为全局组件（如NButton、NInput），对应模板中的<n-button>、<n-input>；组件自身声明的alias也会一并注册；
2. 幂等保护：installTargets数组记录已安装的 App 实例，同一 App 重复app.use(naive)会被直接跳过，不会重复注册；
3. 前缀可定制：create接受componentPrefix选项，因此你也可以通过create({ componentPrefix: 'X' })生成自定义前缀的插件实例。

3.3 CSS 引入的必要性与"免 CSS"说明

import 'naive-ui/dist/lib/index.css'这行在旧版本中用于引入全量样式。需要注意当前版本（v2.45.2）的 README 已经声明："you don't need to import any CSS to use the components"——Naive UI 的样式体系基于 css-render 在运行时按需注入（仓库使用css-render与@css-render/plugin-bem，见 src/_utils/cssr/index.ts），这也是其"无需 webpack loader、无需预处理器变量"的主题定制方案的基础。

因此在实际接入时：

• 全量注册 + 运行时样式注入：通常只需app.use(naive)即可，样式由组件在挂载时自动生成；
• 若你的构建链确实需要显式样式文件，也可以按构建产物引入（dist、es、lib目录均会被发布，见 package.json 的files字段）。

四、从"全量"到"按需"：Tree Shaking 与直接引入

全量app.use(naive)会把 90+ 个组件全部注册进应用。对于追求包体积的线上项目，官方更推荐按需引入。官方文档（demo/pages/docs/import-on-demand/enUS/index.md）说明了 Naive UI 对组件、多语言、主题三者的 Tree Shaking 支持：

Naive UI supports tree shaking for components, locales and themes. By default the component theme is light, locale is enUS, and no extra imports are needed.

4.1 组件直接引入（SFC 中）

在<script setup>中逐个引入所需组件：

<script setup> import { NConfigProvider, NInput, NDatePicker, NSpace } from 'naive-ui' // 主题（按需组合） import { createTheme, inputDark, datePickerDark } from 'naive-ui' // 语言与日期语言 import { zhCN, dateZhCN } from 'naive-ui' </script> <template> <n-config-provider :theme="darkTheme" :locale="zhCN" :date-locale="dateZhCN"> <n-space vertical> <n-input /> <n-date-picker /> </n-space> </n-config-provider> </template>

对应地，各组件模块均从各自目录的 index.ts 汇出xxxProps、组件本体与类型，例如 src/button/index.ts 导出NButton、buttonProps与ButtonProps/ButtonSlots类型。这意味着：

• 类型提示完整（ButtonProps、ButtonSlots等公共类型均从 src/button/index.ts 汇出，见 src/button/index.ts 中的export type * from './src/public-types'）；
• 未引入的组件不会进入最终 bundle，实现 Tree Shaking。

4.2 自动按需引入（推荐工程方案）

对于 SFC 开发，官方推荐两个 unplugin：

• unplugin-auto-import：自动引入 API（如useMessage、useDialog等）；
• unplugin-vue-components：自动解析模板中使用的组件并逐个引入。

在 Vite 的vite.config.ts中配置（摘自 demo/pages/docs/import-on-demand/enUS/index.md 的示例）：

import vue from '@vitejs/plugin-vue' // 按需引入组件与 API import Components from 'unplugin-vue-components/vite' import AutoImport from 'unplugin-auto-import/vite' // 解析器 import { NaiveUiResolver } from 'unplugin-vue-components/resolvers' export default defineConfig({ plugins: [ vue(), AutoImport({ resolvers: [NaiveUiResolver()] }), Components({ resolvers: [NaiveUiResolver()] }) ] })

这样模板中写<n-button>即可自动完成引入与注册，无需手动import，同时保持 Tree Shaking 收益。

4.3 面向命令式 API 的 discrete 引入

Naive UI 的message、dialog、notification、loadingBar等组件支持脱离模板的命令式调用，为此提供了createDiscreteApi（见 src/discrete/index.ts）。它支持按需传入组件集合，例如：

import { createDiscreteApi } from 'naive-ui' const { message } = createDiscreteApi(['message']) message.success('Hello Naive UI')

DiscreteApi与DiscreteApiOptions类型定义在 src/discrete/src/interface.ts。这种方式尤其适合在非组件上下文（如工具模块）中调用 UI 反馈。

五、验证与扩展阅读

接入完成后，可以这样验证是否成功：

1. 在任意页面使用<n-button type="primary">Hello Naive UI</n-button>，页面出现带 Naive UI 默认主题的按钮即表示注册成功；
2. 打开 Vue Devtools，App组件树上应能看到以N前缀注册的组件；
3. 检查构建产物体积：全量注册 vs 按需引入的差异可以在vite build的产物报告中直观对比。

如需继续深入，推荐阅读仓库中的以下内容：

• src/create.ts：插件工厂与组件注册的完整实现（含componentPrefix定制）；
• src/preset.ts：默认全量插件的组装方式；
• demo/pages/docs/installation/enUS/index.md：官方安装文档（含 UMD、字体、图标、设计资源）；
• demo/pages/docs/import-on-demand/enUS/index.md：按需引入与自动导入的完整示例；
• demo/pages/docs/customize-theme：主题定制（createTheme、darkTheme等），主题相关源码位于 src/themes 与 src/styles；
• demo/pages/docs/ssr：服务端渲染接入指南（仓库在 playground/ssr 提供了可运行的 SSR 示例工程）。

六、常见问题速查

七、小结

围绕build/loaders/test/test.md这份极简 "Get Started"，本文把它扩展为一条完整的接入链路：安装 → 全局注册（附底层install机制剖析）→ 按需引入（Tree Shaking / unplugin 自动导入）→ 命令式 API（discrete）→ 验证与排错。无论你是快速原型还是大型生产项目，都可以依据 src/create.ts、src/preset.ts、demo/pages/docs/import-on-demand/enUS/index.md 等仓库证据，选择适合自己的注册策略，并在 Vue 3 + TypeScript 的工程中获得完整的类型支持与主题定制能力。

• 前端
• UI组件