Storybook+Vue3+Vite报Internal server error找不到vite-app.js如何解决

使用Storybook + Vue3 + Vite技术栈开发时，启动服务抛出如下错误：

[vite] Internal server error: No files matching '/virtual:/@storybook/builder-vite/vite-app.js' were found.

• 依赖版本不兼容：@storybook/builder-vite版本与Vite、Storybook核心包、Vue3版本不匹配，是该报错最高发的诱因
• 缓存损坏：Vite预构建缓存、Storybook构建缓存、node_modules依赖存在损坏文件，导致builder-vite无法正常生成虚拟入口文件
• 配置错误：Storybook配置文件中builder字段写法错误，或vite.config中的别名、自定义插件、文件扫描规则拦截了虚拟入口的生成与解析逻辑
• 路径异常：项目存放路径包含非英文字符、空格、转义特殊字符，导致Vite解析虚拟文件路径时匹配失败

按从易到难顺序逐一验证即可：

• 第一步：全量清理缓存后重装依赖
  先删除项目下的node_modules、.storybook/cache-dist、dist文件夹，再清理对应包管理器的缓存，最后重新安装依赖，命令参考：

  # npm用户执行
  npm cache clean --force
  npm install
  
  # pnpm用户执行
  pnpm store prune
  pnpm install
  
  # yarn用户执行
  yarn cache clean
  yarn install
  

  依赖安装完成后重新启动Storybook，验证报错是否消失。
• 第二步：对齐依赖版本
  首先保证所有@storybook/开头的依赖版本号完全一致，再匹配对应Vite版本要求：
  注意：Storybook 8.x版本已将builder-vite能力内置到框架包中，无需额外单独安装@storybook/builder-vite依赖，冗余安装旧版本反而会触发路径冲突
  • Storybook 7.x 适配Vite 3.x ~ 4.x版本，需搭配同版本号的@storybook/builder-vite
  • Storybook 8.x 适配Vite 4.x ~ 5.x版本，直接使用内置的@storybook/vue3-vite框架即可
    版本不对可直接执行升级命令对齐到最新稳定版：

  npx storybook@latest upgrade
  

• 第三步：校验Storybook配置
  打开.storybook/main.ts/.storybook/main.js，移除冗余的builder单独声明，标准配置参考如下：

  /** @type { import('@storybook/vue3-vite').StorybookConfig } */
  const config = {
    stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
    addons: [
      "@storybook/addon-links",
      "@storybook/addon-essentials",
      "@storybook/addon-interactions",
    ],
    framework: {
      name: "@storybook/vue3-vite",
      options: {},
    },
  };
  export default config;
  

• 第四步：排查Vite配置冲突
  临时注释vite.config中所有自定义的alias、plugins、optimizeDeps、resolve规则，重启服务验证。如果报错消失，再逐个放开配置项，定位到具体冲突的规则即可，重点排查是否有自定义插件做了文件路径合法性校验、拦截了virtual:开头的虚拟文件读取逻辑。
• 第五步：检查项目存放路径
  确认项目所在的所有父级文件夹名称均为纯英文，无空格、#、%、&等特殊字符，若存在路径问题直接将项目移动到符合要求的路径下再启动。

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