PhpStorm/WebStorm中Nuxt3自动导入组件被标记为自定义HTML标签

问题复现 #

在JetBrains系列IDE中使用NuxtJS 3开发时，符合自动导入规则的组件无法被IDE正确识别：例如路径为../foo/bar.vue的组件按Nuxt3命名规则对应<FooBar />标签，IDE会将其标记为未知自定义HTML标签。
已确认配置正常的项：

• .nuxt/components.d.ts文件中已生成对应组件的类型映射
• 项目根目录tsconfig.json已正确继承Nuxt自动生成的TS配置，配置内容如下：

{
  // https://v3.nuxtjs.org/concepts/typescript
  "extends": "./.nuxt/tsconfig.json",
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

• nuxi自动生成的./.nuxt/tsconfig.json配置完整，路径映射、include范围均符合要求：

// Generated by nuxi
{
  "compilerOptions": {
    "jsx": "preserve",
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "skipLibCheck": true,
    "strict": false,
    "allowJs": true,
    "noEmit": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "types": [
      "node"
    ],
    "baseUrl": "..",
    "paths": {
      "~~": [
        "."
      ],
      "~~/*": [
        "./*"
      ],
      "@@": [
        "."
      ],
      "@@/*": [
        "./*"
      ],
      "~": [
        "."
      ],
      "~/*": [
        "./*"
      ],
      "@": [
        "."
      ],
      "@/*": [
        "./*"
      ],
      "assets": [
        "assets"
      ],
      "assets/*": [
        "assets/*"
      ],
      "public": [
        "public"
      ],
      "public/*": [
        "public/*"
      ],
      "#app": [
        "node_modules/nuxt/dist/app"
      ],
      "#app/*": [
        "node_modules/nuxt/dist/app/*"
      ],
      "vue-demi": [
        "node_modules/nuxt/dist/app/compat/vue-demi"
      ],
      "@intlify/shared": [
        "node_modules/@intlify/shared/dist/shared.esm-bundler"
      ],
      "@intlify/core-base": [
        "node_modules/@intlify/core-base/dist/core-base.esm-bundler"
      ],
      "@intlify/devtools-if": [
        "node_modules/@intlify/devtools-if/dist/devtools-if.esm-bundler"
      ],
      "vue-i18n": [
        "node_modules/vue-i18n/dist/vue-i18n.esm-bundler"
      ],
      "#auth/runtime": [
        "node_modules/@nuxtjs-alt/auth/dist/runtime"
      ],
      "#auth/runtime/*": [
        "node_modules/@nuxtjs-alt/auth/dist/runtime/*"
      ],
      "#head": [
        "node_modules/nuxt/dist/head/runtime"
      ],
      "#head/*": [
        "node_modules/nuxt/dist/head/runtime/*"
      ],
      "#components": [
        ".nuxt/components"
      ],
      "#imports": [
        ".nuxt/imports"
      ],
      "#build": [
        ".nuxt"
      ],
      "#build/*": [
        ".nuxt/*"
      ]
    }
  },
  "include": [
    "./nuxt.d.ts",
    "../**/*"
  ]
}

• .nuxt/nuxt.d.ts已正确引用components.d.ts声明文件，内容如下：

// Generated by nuxi
/// <reference types="@intlify/nuxt3" />
/// <reference types="@nuxtjs-alt/google-fonts" />
/// <reference types="@nuxtjs-alt/auth" />
/// <reference types="@nuxtjs-alt/axios" />
/// <reference types="@nuxtjs-alt/pinia" />
/// <reference types="@nuxt/content" />
/// <reference types="@nuxtjs/tailwindcss" />
/// <reference types="@nuxt/telemetry" />
/// <reference types="nuxt" />
/// <reference path="types/plugins.d.ts" />
/// <reference path="types/vue-shim.d.ts" />
/// <reference path="types/schema.d.ts" />
/// <reference path="types/content.d.ts" />
/// <reference types="vue-router" />
/// <reference path="types/middleware.d.ts" />
/// <reference path="types/layouts.d.ts" />
/// <reference path="components.d.ts" />
/// <reference path="types/auto-imports.d.ts" />
/// <reference path="imports.d.ts" />
/// <reference path="types/nitro.d.ts" />

export {}

异常效果截图：

结论 #

该问题属于JetBrains IDE的Vue插件兼容问题，大量Nuxt3开发者都遇到过相同情况，上述给出的项目配置没有错误。

解决方案 #

按优先级从高到低尝试以下操作即可解决：

• 安装JetBrains官方出品的Nuxt插件
  打开IDE插件市场搜索Nuxt，认准官方发布的版本，安装完成后重启IDE，插件会自动适配Nuxt3的自动导入规则，组件识别、跳转、补全功能均可正常工作。
• 重建IDE索引
  右键项目中的.nuxt目录，选择Mark Directory as > Not Excluded，避免IDE忽略自动生成的类型文件；之后打开File > Invalidate Caches...，勾选清除文件系统缓存选项，点击Invalidate and Restart等待重启后索引完成即可。
• 关闭误报检查规则
  若前两种方案无效，可手动调整IDE检查规则：打开Settings > Editor > Inspections > HTML > Unknown HTML tag，将该规则的严重等级调整为不高亮，或在自定义标签列表中添加项目使用的组件名规则，即可消除错误标记。

内容的提问来源于stack exchange，提问作者SPQRInc