Vue3 应用实例 API

app 对象

来源：Vue3 官方文档应用实例 API。调用 createApp() / createSSRApp() 返回应用实例 app，所有下面的方法都挂载在该实例上。

一、创建应用

createApp(rootComponent, rootProps?)

创建一个 Vue 应用实例。

• 参数

  1. rootComponent：根组件对象 / .vue 导入组件
  2. rootProps【可选】：传递给根组件的 props 对象

import { createApp } from 'vue'
// 写法1：内联根组件
const app = createApp({
  /* 根组件选项 */
})
// 写法2：导入单文件组件
import App from './App.vue'
const app = createApp(App)

createSSRApp(rootComponent, rootProps?)

以 SSR 激活模式 创建应用实例，参数用法与 createApp 完全一致，用于服务端渲染场景。

---

二、DOM 挂载 / 卸载

app.mount(rootContainer)

将应用挂载到真实 DOM 容器上，每个实例只能调用 1 次。

• 参数：DOM 元素 / CSS 选择器字符串（取第一个匹配元素）
• 返回值：根组件实例

app.mount('#app')
// 也可以传入DOM对象
app.mount(document.body.firstChild)

注意：

1. 如果组件有template/render，会替换容器内原有 DOM ；没有则把容器innerHTML当做模板（仅完整构建版本）
2. SSR 激活模式下，是激活已有 DOM，不是覆盖；出现激活不匹配会修正 DOM。

app.unmount()

卸载已经挂载的应用实例，触发整个组件树所有组件的 unmounted 卸载生命周期钩子。

app.unmount()

app.onUnmount(callback)

注册回调，当应用实例被卸载时执行。

app.onUnmount(()=>{
  console.log('应用被卸载')
})

---

三、全局注册

app.component(name, component?)

全局注册 / 获取组件。

• 两个参数：注册全局组件
• 只传名字：获取已经注册的全局组件（找不到返回undefined）

//注册
app.component('MyComponent', {
  /*组件选项 */
})
//获取
const MyComponent = app.component('MyComponent')

app.directive(name, directive?)

全局注册 / 获取自定义指令。

• 双参：注册全局指令；单参：获取指令

//对象形式指令
app.directive('my-directive', {
  mounted(el){}
})
//函数简写指令
app.directive('my-directive',(el)=>{})
//获取指令
const dir = app.directive('my-directive')

app.use(plugin, ...options)

安装插件。

• 插件可以是：①拥有install(app)方法的对象；②直接是 install 函数
• 重复调用同一个插件，只会执行一次安装
• 后续参数全部作为选项传递给插件的 install

import MyPlugin from './plugins/MyPlugin'
app.use(MyPlugin, { someOption:true })

app.mixin(mixinObject)

注册全局 mixin，会作用到本应用每一个组件实例上。

⚠️官方不推荐新项目使用，仅为向后兼容，优先使用组合式函数替代 mixin。

app.mixin({
  created(){
    console.log('每个组件创建都执行')
  }
})

---

四、依赖注入（应用层级 provide/inject）

app.provide(key, value)

应用层提供值，本应用下所有后代组件都可以使用inject注入拿到 。 key 支持字符串、Symbol、InjectionKey。

app.provide('msg','hello')

后代组件中获取：

//组合式
import {inject} from 'vue'
setup(){
  const msg = inject('msg')
}

//选项式
export default {
  inject:['msg'],
  created(){
    console.log(this.msg)
  }
}

app.runWithContext(fn)

✨Vue3.3 + 新增。在没有组件实例上下文的时候，允许执行回调，此时inject()可以读取 app.provide 提供的值，返回回调函数返回值。

app.provide('id',1)
const res = app.runWithContext(()=> inject('id'))
console.log(res) //1

app.version

字符串，当前应用使用的 Vue 版本，插件内部很有用，可以做版本判断逻辑。

export default {
  install(app){
    const v = Number(app.version.split('.')[0])
    if(v <3) console.warn('插件需要Vue3')
  }
}

---

五、app.config 应用全局配置对象

必须mount 挂载之前修改 config 配置才生效！

app.config.errorHandler

全局捕获应用中未捕获错误的处理器。捕获来源：渲染、事件处理器、生命周期、setup、侦听器、自定义指令、transition 钩子。

app.config.errorHandler = (err, instance, info)=>{
  // err：错误对象
  // instance：出错组件实例，可以为null
  // info：错误来源标记，生产环境是简短错误码
}

app.config.warnHandler

自定义 Vue 运行时警告处理，仅开发环境生效，生产会被忽略，用于收集 / 过滤警告信息。

app.config.warnHandler = (msg, instance, trace)=>{
  // trace：组件调用栈字符串
}

app.config.performance

布尔值，开启浏览器 devtools 性能面板追踪组件初始化、编译渲染更新性能；仅开发模式，浏览器支持 performance.mark 才有效。

app.config.performance = true

app.config.compilerOptions

运行时编译器配置。

⚠️只在完整构建（带编译器 vue.js）生效；vite/webpack 项目（runtime-only）要在构建工具插件配置 compilerOptions，不能在这里写！

表格

属性	说明
isCustomElement(tag)	判断标签是否是原生 web components 自定义元素，返回 true，则 Vue 不作为组件解析，直接渲染原生标签
whitespace	condense(默认)/preserve，控制模板空格换行压缩策略
delimiters	修改插值语法分隔符，默认['{{','}}']，避免和后端模板冲突
comments	布尔，生产环境是否保留模板 HTML 注释，默认 false，生产删除注释

示例：

app.config.compilerOptions.isCustomElement = tag=> tag.startsWith('ion-')
app.config.compilerOptions.delimiters = ['${','}']

app.config.globalProperties

Vue3 替代 Vue2 的Vue.prototype，注册全局属性，所有组件实例this和模板可以直接访问。组件自身属性优先级高于 globalProperties。

app.config.globalProperties.$api = ()=>{}

组件中使用：

mounted(){
  this.$api()
}

app.config.optionMergeStrategies

自定义组件选项合并策略，针对自定义选项；mixin、组件继承合并的时候会调用。key 是自定义选项名字，函数接收(父选项值，子选项值)返回合并结果。

app.config.optionMergeStrategies.myOption = (parentVal,childVal)=>{
  return (parentVal||'') + (childVal||'')
}

app.config.idPrefix

给useId()生成的 id 字符串添加统一前缀，Vue3.3+。

app.config.idPrefix = 'myapp'
//组件中 const id = useId() // myapp:0

app.config.throwUnhandledErrorInProduction

布尔，默认 false。生产环境默认错误只打印控制台不抛出；设置 true，生产也会抛出未捕获异常，方便错误监控服务捕获异常。

app.config.throwUnhandledErrorInProduction = true

关键总结

1. 每个createApp得到独立 app 实例，实例之间配置、全局组件、指令互不干扰；
2. app.config必须在mount()挂载前设置；
3. compilerOptions仅完整构建版本生效；vite/vue-cli 项目要在构建插件配置；
4. 尽量避免app.mixin()全局混入；优先组合式函数；
5. globalProperties替代 Vue2 原型，组合式 setup 内部拿不到 this，建议尽量少用；
6. app.provide是应用级别注入 ，大于组件树 provide；runWithContext解决无组件上下文调用 inject