Cypress Vue组件测试导入Ref类型崩溃：模块未导出'Ref'

问题描述 #

编写了一个Cypress组件测试，仅用于挂载组件并断言其存在。组件为TypeScript编写，导入了Vue的Ref类型，但运行测试时触发如下错误：

请求的模块'/__cypress/src/node_modules/.vite/deps/vue.js?v=861dc0d7'未提供名为'Ref'的导出

已在Cypress的tsconfig.json的types中添加了vue，但问题仍未解决。

相关配置与代码 #

tsconfig.json #

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress", "vue", "node"],
    "baseUrl": "./",
    "allowJs": true,
    "paths": {
      "~": ["."]
    }
  },
  "include": ["**/*.ts", "**/*.js"]
}

cypress.config.js #

const { defineConfig } = require("cypress")

module.exports = defineConfig({
    component: {
        supportFile: "cypress/support/component.ts",
        devServer: {
            framework: "vue",
            bundler: "vite",
        },
    },
})

组件代码（MyComponent.vue） #

<template>
    <div class="my-component">
        {{ counter }}
    </div>
</template>

<script setup lang="ts">
import type { Ref } from "vue"

const counter: Ref<number> = ref(1)
</script>

测试代码（MyComponent.cy.ts） #

import MyComponent from "./MyComponent.vue"

beforeEach(() => {
    cy.mount(MyComponent)
})

it("Test My Component", () => {
    cy.get(".my-component").should("exist")
})

问题原因与解决方法 #

这个错误的核心是Vue类型导入方式与运行时导出不匹配，加上Cypress组件测试环境的模块解析逻辑导致的。以下是具体解决步骤：

1. 修正Ref类型导入语法 #

Vue 3中Ref是类型而非运行时值，需使用符合TS 4.5+规范的类型导入语法，或者直接省略显式类型让Vue自动推断：

<script setup lang="ts">
// 写法1：使用TS 4.5+的type-only导入语法
import { type Ref } from "vue"
const counter: Ref<number> = ref(1)

// 写法2：省略显式类型，依赖Vue自动推断
const counter = ref(1)
</script>

2. 检查并安装必要依赖 #

确保已安装Cypress Vue相关插件，若未安装执行：

npm install @cypress/vue @cypress/vite-dev-server --save-dev

3. 调整tsconfig.json配置 #

添加模块解析规则并确保Vue单文件组件被TypeScript解析：

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress", "vue", "node"],
    "baseUrl": "./",
    "allowJs": true,
    "paths": {
      "~": ["."]
    },
    "moduleResolution": "node",
    "module": "esnext"
  },
  "include": ["**/*.ts", "**/*.js", "**/*.vue"]
}

4. 明确Cypress的Vue版本 #

在配置中指定Vue 3版本，避免自动检测出错：

const { defineConfig } = require("cypress")

module.exports = defineConfig({
    component: {
        supportFile: "cypress/support/component.ts",
        devServer: {
            framework: "vue",
            bundler: "vite",
            frameworkVersion: "3.x"
        },
    },
})

内容的提问来源于stack exchange，提问作者Cédric Bloem