Vue script setup 中组件静默消失的原因：一次命名冲突排查（1）：从静默消失定位到命名冲突

最小复现

先写一个最小化 SFC。

<template>
  <popup-status :message="popupStatus.message" :type="popupStatus.type" />
</template>

<script setup lang="ts">
import { PopupStatus } from './components';

const popupStatus = { message: 'hello', type: 'success' };
</script>

直觉上，<popup-status> 应该对应导入的 PopupStatus 组件，:message 和 :type 读取本地状态对象 popupStatus。

编译结果却指向了状态对象。

可以用 vue/compiler-sfc 做一个最小编译实验：

import { parse, compileScript, compileTemplate } from 'vue/compiler-sfc';

const source = `
<template>
  <popup-status :message="popupStatus.message" :type="popupStatus.type" />
</template>

<script setup lang="ts">
import { PopupStatus } from './components';

const popupStatus = { message: 'hello', type: 'success' };
</script>
`;

// 1. parse 把 .vue 文件拆成 SFC descriptor，也就是 template、script、style 这些块。
const { descriptor } = parse(source, { filename: 'Conflict.vue' });

// 2. compileScript 处理 <script setup>，返回 script 编译结果。
const compiledScript = compileScript(descriptor, { id: 'demo' });

// 3. compileTemplate 处理 <template>，生成 render 函数。
//    这里把 compiledScript.bindings 传进去，是为了让模板编译器知道模板里每个名字来自哪里。
const template = compileTemplate({
  id: 'demo',
  filename: 'Conflict.vue',
  source: descriptor.template.content,
  compilerOptions: {
    bindingMetadata: compiledScript.bindings
  }
});

console.log(compiledScript.bindings);
console.log(compiledScript.content);
console.log(template.code);

先看 compiledScript。它是 compileScript() 返回的「script 编译结果」对象，已经不再是原来的 <script> 标签。这个对象包含 attrs、imports、map、scriptAst、scriptSetupAst、deps 等信息；这里只关注和当前问题直接相关的两个字段：

• compiledScript.bindings 是给编译器继续使用的元数据，描述每个顶层绑定是什么类型。
• compiledScript.content 是一个「内容为代码的字符串」，也就是 compileScript() 生成出来、后续会交给打包器继续处理并输出到产物里的组件代码。

第一个 console.log(compiledScript.bindings) 的输出是：

// compiledScript.bindings
{
  "PopupStatus": "setup-maybe-ref",
  "popupStatus": "setup-const"
}

第二个 console.log(compiledScript.content) 的输出是一段代码字符串。为了阅读方便，这里直接按代码格式展示：

import { defineComponent as _defineComponent } from 'vue'
import { PopupStatus } from './components';

export default /*@__PURE__*/_defineComponent({
  __name: 'Conflict',
  setup(__props, { expose: __expose }) {
    __expose();

    const popupStatus = { message: 'hello', type: 'success' };

    const __returned__ = {
      popupStatus,
      get PopupStatus() { return PopupStatus }
    }
    Object.defineProperty(__returned__, '__isScriptSetup', {
      enumerable: false,
      value: true
    })
    return __returned__
  }
})

从这段产物可以看到，<script setup> 会被 compileScript 改成一个标准 defineComponent 组件，浏览器执行的是编译后的代码。原来的顶层变量会放进 setup()，最后通过 __returned__ 暴露给模板。

所以 bindings 和 __returned__ 是对应的：

{
  "PopupStatus": "setup-maybe-ref", // import 进来的组件变量
  "popupStatus": "setup-const"      // 本地 const 状态
}

接着看 template。它是 compileTemplate() 返回的「template 编译结果」对象，也不只有 code，还包括 ast、tips、errors、map 等信息。当前只关注 template.code，因为它能直接看出 <popup-status> 最终被编译成了什么。

第三个 console.log(template.code) 的输出是：

import { openBlock as _openBlock, createBlock as _createBlock } from "vue";

export function render(_ctx, _cache, $props, $setup, $data, $options) {
  return (_openBlock(), _createBlock($setup["popupStatus"], {
    message: $setup.popupStatus.message,
    type: $setup.popupStatus.type
  }, null, 8 /* PROPS */, ["message", "type"]));
}

compiledScript.content 里有 import 和 export default，template.code 里也有 import 和 export function render。它们是两个模块形态的代码片段，还要由构建插件组装成最终组件。

compileScript() 和 compileTemplate() 是底层编译 API，分别处理 script 和 template；在 Vite 项目中，@vitejs/plugin-vue 负责衔接两份产物。

@vitejs/plugin-vue 的 transformMain 会先生成 script 和 template 两段代码，并把 template 的 render 记录成要挂到组件上的属性。随后它把这些代码片段放进同一个 output 数组里，最后通过 _export_sfc(_sfc_main, [['render', _sfc_render]]) 导出最终组件。

插件需要先拿到组件主体和 render 的内部绑定，把 render 挂到组件上，再导出组装后的组件，因此会做两类改写。

第一类是把 script 的默认导出改成内部变量。@vitejs/plugin-vue 里有一个固定的组件变量名 _sfc_main，compileScript() 在合适的时候会直接生成 const _sfc_main = ...；否则插件也会用 rewriteDefault() 把默认导出改写成这个变量。

scriptIdentifier 就是 _sfc_main。这一步的目的很直接：先拿到组件对象，但暂时不要 export default。

第二类是把 template 的具名导出改成内部 render 函数。compileTemplate() 原本输出的是 export function render(...)，而 Vite 插件在把 template 合进主模块时，会把它改成 function _sfc_render(...)。

transformTemplateInMain 做的核心事情就是把 export function render 或 export const render 改成 _sfc_render 这种内部名字。

下面的伪代码展示 script、template 和最终默认导出的关系，是简化后的模块结构，不对应某一个源码文件：

import { defineComponent as _defineComponent } from 'vue';
import { openBlock as _openBlock, createBlock as _createBlock } from 'vue';
import { PopupStatus } from './components';
import _export_sfc from 'plugin-vue:export-helper';

const _sfc_main = /* @__PURE__ */ _defineComponent({
  __name: 'Conflict',
  setup(__props, { expose: __expose }) {
    __expose();

    const popupStatus = { message: 'hello', type: 'success' };

    const __returned__ = {
      popupStatus,
      get PopupStatus() { return PopupStatus }
    };

    Object.defineProperty(__returned__, '__isScriptSetup', {
      enumerable: false,
      value: true
    });

    return __returned__;
  }
});

function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
  return (_openBlock(), _createBlock($setup["popupStatus"], {
    message: $setup.popupStatus.message,
    type: $setup.popupStatus.type
  }, null, 8 /* PROPS */, ["message", "type"]));
}

export default /*#__PURE__*/_export_sfc(_sfc_main, [
  ['render', _sfc_render]
]);

最终模块只有一个默认导出；compiledScript.content 贡献的是组件主体 _sfc_main，template.code 贡献的是渲染函数 _sfc_render，构建插件把后者挂回前者，再导出完整组件。

openBlock 用于打开一个 block，createBlock 用于在里面创建一个有意义的渲染块。当前需要关注的是 createBlock 的第一个参数，它表示要渲染的组件类型或标签类型。

真正决定绑定的是这一句：

_createBlock($setup["popupStatus"], ...)

$setup 是 render 函数运行时收到的参数，可以粗略理解成前面 setup() 返回给模板使用的对象。它的具体值要等组件运行起来以后才有。

但 ["popupStatus"] 不是运行时动态决定的。它已经在编译阶段被写死进 render 函数了。问题发生在编译阶段：模板编译器已经决定 <popup-status> 要读取 $setup["popupStatus"]，运行时只是照着这段代码执行。

前面的 __returned__ 里同时有 popupStatus 和 PopupStatus。一旦编译产物固定成 $setup["popupStatus"]，运行时即使 $setup 里也存在真正的组件 PopupStatus，这里也不会再去重新选择它。

Vue 编译器把这个普通对象当成了组件：

const popupStatus = { message: 'hello', type: 'success' };

现场的完整组件导入

import { ActionFooter, EmptyState, KeySelectionTree, PopupStatus, SettingsForm } from './components';

现场的完整状态解构

const {
  copyConsoleWriteScript,
  copyConsoleWriteScriptIsLoading,
  hasKeySelectionPreview,
  keySelectionOverrides,
  popupStatus,
  primaryActionIsLoading,
  readCurrentTable,
  selectedTagKeys,
  settings,
  targetTabsSnapshot,
  updateSettings,
  writeSelectedKeys
} = usePopupFlow();

改名后的完整状态解构

const {
  copyConsoleWriteScript,
  copyConsoleWriteScriptIsLoading,
  hasKeySelectionPreview,
  keySelectionOverrides,
  popupFeedback,
  primaryActionIsLoading,
  readCurrentTable,
  selectedTagKeys,
  settings,
  targetTabsSnapshot,
  updateSettings,
  writeSelectedKeys
} = usePopupFlow();

改名后的产物

把状态对象改成 popupFeedback：

<template>
  <popup-status :message="popupFeedback.message" :type="popupFeedback.type" />
</template>

<script setup lang="ts">
import { PopupStatus } from './components';

const popupFeedback = { message: 'hello', type: 'success' };
</script>

再编译一次，结构会变成这样：

// compiledScript.bindings
{
  "PopupStatus": "setup-maybe-ref",
  "popupFeedback": "setup-const"
}

// compiledScript.content 里的返回对象
const __returned__ = {
  popupFeedback,
  get PopupStatus() { return PopupStatus }
}
return __returned__

// template.code 里的 render 函数
import { openBlock as _openBlock, createBlock as _createBlock } from "vue";

export function render(_ctx, _cache, $props, $setup, $data, $options) {
  return (_openBlock(), _createBlock($setup["PopupStatus"], {
    message: $setup.popupFeedback.message,
    type: $setup.popupFeedback.type
  }, null, 8 /* PROPS */, ["message", "type"]));
}

这次 __returned__ 里没有 popupStatus，<popup-status> 的候选名只会命中 PopupStatus。所以 render 函数里变成了正确结果：

_createBlock($setup["PopupStatus"], ...)

Vue 2.7 之前的第三方方言

Vue 2.7 发布前，常见的 <script setup> 方言主要是 Anthony Fu 的 unplugin-vue2-script-setup。它的 README 说明，Vue 2.7 已经内置 Composition API 和 <script setup>，因此不再需要这个插件；插件进入维护模式，只支持 Vue 2.6 或更早版本。

unplugin-vue2-script-setup 的说明见 README。这里讨论的是这个插件的最后版本 v0.11.4，不是 Vue 2.7 官方编译器实现。

这个插件的核心方式是先改写源码。transformVue() 会解析 SFC，调用 transformScriptSetup() 生成普通 <script> 内容，然后用这个 <script> 替换原来的 <script setup> 块。

const sfc = await parseSFC(input, id);

const { code } = transformScriptSetup(sfc, options);

if (code) {
  const block = `<script ${attr}>\n${code}\n</script>`;

  s.remove(sfc.script.start, sfc.script.end);

  if (sfc.scriptSetup.start !== sfc.scriptSetup.end) {
    s.overwrite(sfc.scriptSetup.start, sfc.scriptSetup.end, block);
  }

  // ...
}

对应源码在 transform.ts。它的作用是在 Vue 2 编译器前面先做一次源码转译，而不是让 Vue 2 编译器原生理解 <script setup>。

它还会先从模板里收集组件 tag。<popup-status> 会被转成 PopupStatus，放进 template.components。

const result = codeOfTemplate
  ? findReferencesForSFC(codeOfTemplate)
  : undefined;

return {
  // ...
  template: {
    components: new Set(result?.components.map(pascalize)),
    directives: new Set(/* ... */),
    identifiers: new Set(result?.identifiers)
  },
  scriptSetup,
  script
};

随后 transformScriptSetup() 会用这个组件名去顶层声明里找匹配项：

const components = Array.from(template.components)
  .map(
    component =>
      declarationArray.find(declare => declare === component)
      ?? declarationArray.find(declare => pascalize(declare) === component),
  )
  .filter(notNullish);

这段顺序很关键。假设代码里同时有：

import { PopupStatus } from './components';

const popupStatus = { message: 'hello', type: 'success' };

<popup-status> 对应的组件名是 PopupStatus。插件会先用 declare === component 精确命中导入的 PopupStatus，只有精确找不到时，才会尝试 pascalize(popupStatus)。因此在这个组合里，popupStatus 这个普通状态对象不会抢走组件 tag。

最后插件会把命中的组件注入普通组件选项，生成效果类似：

__sfc_main.components = Object.assign(
  { PopupStatus },
  __sfc_main.components,
);

对应源码在 parseSFC.ts 和 transformScriptSetup.ts。组件注入在 transformScriptSetup.ts。

所以，Vue 2.6 或更早版本配这个插件时，当前文章里的典型问题不能直接照搬。它会先把导入组件挂到 components 上，静态组件 tag 后续走普通 Vue 2 组件解析；而 Vue 3.1+ / Vue 2.7 官方 <script setup> 的问题点，是编译器把静态组件 tag 解析成 setup 绑定。

这不表示 2.6 插件完全没有名字风险。如果模板里只有一个叫 popupStatus 的普通对象可以被 pascalize() 匹配到，它仍然可能被注入 components。只是对「导入组件 PopupStatus + 同名状态对象 popupStatus」这个真实案例来说，2.7 之前的 antfu 插件不会按本文这条 $setup["popupStatus"] 路径失败。