Vue 3 全局 API 完全指南
本文档从零开始讲解 Vue 3 的全局 API：如何创建应用（createApp）、应用实例上有哪些方法（mount、component、directive、use、provide、config），以及从 vue 引入的通用 API（nextTick、h、defineComponent、defineAsyncComponent）和工具函数（isRef、toRef、toRefs 等），配有大量示例，适合新手系统学习。
一、什么是“全局 API”？
1.1 两类“全局”含义
在 Vue 3 里，“全局 API”常指两类：
- 应用相关：用来创建应用、配置应用实例的 API，如 createApp、app.mount、app.component。
- 从 ‘vue’ 引入的 API：在任意地方 import { ref, nextTick } from ‘vue’ 就能用的函数，如 ref、reactive、nextTick、defineComponent。
它们都不依赖“当前组件”，可以在 main.js、在组件里、在工具函数里使用。
本文先讲应用创建与实例，再讲常用全局 API 和工具函数。
1.2 和 Vue 2 的差异
Vue 2 里很多“全局”能力挂在 Vue 上（如 Vue.component、Vue.directive）。
Vue 3 改为按应用划分：createApp() 得到一个应用实例，component、directive、use 等都挂在这个实例上，这样多个应用（如多页或微前端）可以互不干扰。
二、createApp —— 创建应用
2.1 作用
createApp 根据你传入的根组件创建一个 Vue 应用实例。
这个实例上有 mount、component、directive、use、provide、config 等方法，用来挂载应用、注册全局组件/指令、使用插件等。
2.2 基本用法
// main.js
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
app.mount('#app')- createApp(App)：以 App 为根组件创建应用。
- app.mount(‘#app’)：把应用挂载到 id 为 app 的 DOM 节点上；挂载后返回根组件实例（一般不需要用）。
2.3 传入根组件的 props（可选）
若根组件需要 props，可在 createApp 的第二个参数传入：
createApp(App, { id: 1, title: '标题' }).mount('#app')根组件里用 defineProps 或 props 选项接收即可。
三、应用实例方法
createApp() 返回的对象就是应用实例，常用方法如下。
3.1 app.mount(selector)
作用： 把应用挂载到指定 DOM 节点上；节点由 querySelector 查找（如 ‘#app’、‘.container’）。
只能挂载一次，重复调用会报错。
const app = createApp(App)
app.mount('#app')3.2 app.unmount()
作用： 卸载已挂载的应用，从 DOM 上移除根组件并销毁。
可用于“单页里切换成别的框架”或测试场景。
const app = createApp(App)
const instance = app.mount('#app')
app.unmount()3.3 app.component(name, component?)
作用： 注册全局组件（两个参数），或获取已注册的组件（只传一个 name）。
注册后，任意组件的模板里都可以直接用 ，无需再 import。
import MyButton from './components/MyButton.vue'
app.component('MyButton', MyButton)
app.component('MyButton', MyButton)模板里： 或 。
只传名字：const Comp = app.component(‘MyButton’)。
3.4 app.directive(name, directive?)
作用： 注册全局自定义指令（两个参数），或获取已注册的指令（只传 name）。
注册后，任意模板里都可写 v-xxx。
app.directive('focus', {
mounted(el) {
el.focus()
}
})模板里：。
详见《Vue3自定义指令.md》。
3.5 app.use(plugin, options?)
作用： 安装插件。
插件可以是一个对象（有 install 方法）或函数（本身即 install）；Vue 会传入 app 和 options。
import MyPlugin from './plugin'
app.use(MyPlugin, { someOption: true })常见插件：Vue Router（app.use(router)）、Pinia（app.use(pinia)）。
3.6 app.provide(key, value)
作用： 在应用级别提供数据，所有子组件都可以 inject(key) 拿到。
适合“全局”主题、语言、用户信息等。
app.provide('theme', 'dark')
app.provide('api', axiosInstance)任意子组件：inject(‘theme’)、inject(‘api’)。
3.7 app.config
作用： 应用配置对象。
常用子属性：
- app.config.globalProperties：往上面挂属性后，所有组件的 this.xxx（或模板里）都能访问，相当于“全局属性”。
- app.config.errorHandler：全局错误处理函数。
- app.config.warnHandler：全局警告处理函数。
- app.config.performance：是否开启性能追踪等。
示例：挂全局属性
app.config.globalProperties.$api = axiosInstance
app.config.globalProperties.$msg = (text) => alert(text)组件里：this.$api.get(‘/user’)、this.$msg(‘成功’)。
在 里没有 this，可用 getCurrentInstance()?.appContext.config.globalProperties 或更推荐用 provide/inject 传依赖。
四、从 ‘vue’ 引入的常用全局 API
以下 API 在需要的地方 import { xxx } from ‘vue’ 即可使用，不依赖“当前应用”或“当前组件”。
4.1 nextTick
作用： 在 Vue 把数据变化应用到 DOM 之后再执行你传入的回调（或返回 Promise）。
用于“改完数据立刻操作 DOM”的场景，如滚动到底部、focus 输入框。
import { nextTick } from 'vue'
this.list.push(newItem)
await nextTick()
this.$refs.list.scrollTop = this.$refs.list.scrollHeight或在 里：
import { nextTick } from 'vue'
await nextTick()
inputRef.value?.focus()4.2 h（渲染函数）
作用： 创建 VNode（虚拟节点），用于手写渲染函数或 JSX 里。
多数情况用模板即可，不需要直接写 h；在高级场景（如写高阶组件、渲染函数）会用到。
import { h } from 'vue'
export default {
render() {
return h('div', { class: 'box' }, [h('p', null, '内容')])
}
}4.3 defineComponent
作用： 用配置对象定义一个组件，并得到更好的 TypeScript 类型推断；export default defineComponent({ … }) 和 export default { … } 在运行上等价，主要是类型和提示更好。
import { defineComponent } from 'vue'
export default defineComponent({
name: 'MyComp',
props: {
title: String
},
setup(props) {
return {}
}
})4.4 defineAsyncComponent
作用： 定义异步组件（动态 import），加载完成前可显示 loading 或占位。
import { defineAsyncComponent } from 'vue'
const AsyncComp = defineAsyncComponent(() => import('./Heavy.vue'))
const AsyncWithOptions = defineAsyncComponent({
loader: () => import('./Heavy.vue'),
delay: 200,
timeout: 3000,
loadingComponent: LoadingComp,
errorComponent: ErrorComp
})在 components 里注册或在模板里用 即可。
五、响应式相关 API（简要）
这些从 ‘vue’ 引入，在组件或组合式函数里大量使用；这里只列名字和一句话用途，详细见对应文档。
| API | 用途 |
|---|---|
| ref | 创建响应式引用（任意类型） |
| reactive | 创建响应式对象 |
| computed | 计算属性 |
| watch | 侦听单个或多个源 |
| watchEffect | 自动收集依赖的侦听 |
| readonly | 只读代理 |
| shallowRef / shallowReactive | 浅层响应式 |
详见《Vue3组合式API.md》《Vue3计算属性.md》《Vue3监听属性.md》。
六、生命周期 API（简要）
在 setup 或 里用 onXxx 注册生命周期：
import { onMounted, onUnmounted } from 'vue'
onMounted(() => {})
onUnmounted(() => {})详见《Vue3中生命周期钩子.md》。
七、工具函数（isXxx、toRef、toRefs、unref）
7.1 isRef / isReactive / isReadonly / isProxy
作用： 判断一个值是不是 ref、reactive 对象、readonly 代理、reactive/readonly 代理。
import { ref, reactive, isRef, isReactive } from 'vue'
const r = ref(0)
const obj = reactive({})
console.log(isRef(r))
console.log(isReactive(obj))7.2 toRef / toRefs
toRef：把对象的一个属性转成 ref，且和原对象保持同步。
toRefs：把 reactive 对象的每个属性都转成 ref，便于解构后仍保持响应式。
import { reactive, toRef, toRefs } from 'vue'
const state = reactive({ count: 0, name: '' })
const countRef = toRef(state, 'count')
const { count, name } = toRefs(state)详见《Vue3中ref和reactive区别.md》。
7.3 unref
作用： 若传入的是 ref 则返回 .value，否则返回本身。
用于“不知道是 ref 还是普通值”时统一当值用。
import { unref } from 'vue'
const a = ref(1)
console.log(unref(a))
console.log(unref(2))八、provide / inject（组合式里）
在 setup 里用 provide(key, value)、inject(key) 做跨层级传值；应用级可用 app.provide（见上文）。
import { provide, inject } from 'vue'
provide('theme', 'dark')
const theme = inject('theme')九、version
作用： 当前使用的 Vue 版本号（字符串）。
import { version } from 'vue'
console.log(version)十、完整示例：main.js 里使用全局 API
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { createPinia } from 'pinia'
import MyButton from './components/MyButton.vue'
const app = createApp(App)
const pinia = createPinia()
app.use(router)
app.use(pinia)
app.component('MyButton', MyButton)
app.directive('focus', {
mounted(el) {
el.focus()
}
})
app.provide('api', axiosInstance)
app.config.globalProperties.$msg = (t) => alert(t)
app.mount('#app')十一、全局 API 速查表
| API | 来源 | 作用 |
|---|---|---|
| createApp | vue | 创建应用实例 |
| app.mount | 应用实例 | 挂载应用 |
| app.unmount | 应用实例 | 卸载应用 |
| app.component | 应用实例 | 注册/获取全局组件 |
| app.directive | 应用实例 | 注册/获取全局指令 |
| app.use | 应用实例 | 安装插件 |
| app.provide | 应用实例 | 应用级 provide |
| app.config | 应用实例 | 应用配置（含 globalProperties） |
| nextTick | vue | DOM 更新后执行 |
| h | vue | 创建 VNode |
| defineComponent | vue | 定义组件（类型友好） |
| defineAsyncComponent | vue | 定义异步组件 |
| ref / reactive / computed / watch | vue | 响应式与侦听 |
| onMounted / onUnmounted 等 | vue | 生命周期 |
| provide / inject | vue | 依赖注入 |
| isRef / toRef / toRefs / unref | vue | 工具函数 |
| version | vue | Vue 版本号 |
十二、学习建议
- 先掌握 createApp、app.mount、app.use（装路由、Pinia）、app.component（全局组件，按需用）。
- 在组件里常用 nextTick；defineComponent、defineAsyncComponent 需要时再查。
- app.config.globalProperties 可挂全局属性，但更推荐 app.provide 或 Pinia 做“全局”数据。
- 响应式、生命周期、provide/inject 的细节见对应专题文档。
把本文档里的 main.js 示例在项目里改一改、跑一遍，会掌握得更牢。祝你学习顺利。