使用pnpm时Astro dev触发vite:import-analysis报错求助

异常报错信息 #

运行astro dev时触发Vite语法解析错误：

5:21:51 PM [vite] Internal server error: Failed to parse source for import analysis because the content contains invalid JS syntax. If you are using JSX, make sure to name the file with the .jsx or .tsx extension.
  Plugin: vite:import-analysis
  File: /project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/client/env.mjs:4:0
  1  |  const context = (() => {
     |  ^
  2  |      if (typeof globalThis !== 'undefined') {
  3  |          return globalThis;
      at formatError (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:43993:46)
      at TransformContext.error (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:43989:19)
      at TransformContext.transform (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:41740:22)
      at async Object.transform (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:44283:30)
      at async loadAndTransform (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:54950:29)
      at async viteTransformMiddleware (file:///project/node_modules/.pnpm/vite@4.4.9_@types+node@20.7.0/node_modules/vite/dist/node/chunks/dep-df561101.js:64345:32)

疑问与背景 #

1. 为何Vite会分析node_modules目录下的文件？
2. node_modules/.pnpm中带+的目录是pnpm的什么机制？

➜ ls node_modules/.pnpm/ | grep vite
@astrojs+preact@3.0.0_@babel+core@7.23.0_preact@10.17.1_vite@4.4.9
@astrojs+react@3.0.2_@types+react-dom@18.0.6_@types+react@18.0.21_react-dom@18.0.0_react@18.0.0_vite@4.4.9
@preact+preset-vite@2.5.0_@babel+core@7.23.0_preact@10.17.1_vite@4.4.9
@prefresh+vite@2.4.1_preact@10.17.1_vite@4.4.9
@vitejs+plugin-react@4.1.0_vite@4.4.9
vite@4.4.9_@types+node@20.7.0
vitefu@0.2.4_vite@4.4.9

3. 同仓库中另一个使用Preact的Astro项目运行正常，确定是pnpm依赖处理机制影响了Vite。

项目配置 #

package.json #

"dependencies": {
        "@astrojs/react": "3.0.2",
        "@astrojs/tailwind": "5.0.0",
        "@aws-amplify/ui-react": "5.3.1",
        "@radix-ui/react-avatar": "^1.0.3",
        "@radix-ui/react-dropdown-menu": "^2.0.5",
        "@radix-ui/react-select": "^1.2.2",
        "@radix-ui/react-slot": "1.0.2",
        "astro": "3.0.12",
        "aws-amplify": "^5.3.11",
        "class-variance-authority": "0.7.0",
        "clsx": "1.2.1",
        "lucide-react": "0.105.0-alpha.4",
        "react": "18.0.0",
        "react-dom": "18.0.0",
        "tailwind-merge": "1.13.2",
        "tailwindcss-animate": "1.0.6",
        "zod": "^3.22.2"
    },
    "devDependencies": {
        "@types/react": "18.0.21",
        "@types/react-dom": "18.0.6",
        "tailwindcss": "3.3.2",
        "typescript": "5.1.6"
    }

pnpm-lock.yaml片段 #

/@vitejs/plugin-react@4.1.0(vite@4.4.9):
    resolution: {integrity: sha512-rM0SqazU9iqPUraQ2JlIvReeaxOoRj6n+PzB1C0cBzIbd8qP336nC39/R9yPi3wVcah7E7j/kdU1uCUqMEU4OQ==}
    engines: {node: ^14.18.0 || >=16.0.0}
    peerDependencies:
      vite: ^4.2.0
    dependencies:
      '@babel/core': 7.23.0
      '@babel/plugin-transform-react-jsx-self': 7.22.5(@babel/core@7.23.0)
      '@babel/plugin-transform-react-jsx-source': 7.22.5(@babel/core@7.23.0)
      '@types/babel__core': 7.20.2
      react-refresh: 0.14.0
      vite: 4.4.9(@types/node@20.7.0)
    transitivePeerDependencies:
      - supports-color
    dev: false

  /astro@3.0.12(@types/node@20.7.0):
    resolution: {integrity: sha512-nDLI9OGEjYIX90a1Md1orqyurPxqXTWTy7Sm3ZsWl5dpzSjcUXo3VB/GTvNjAMS9sE40BOxhay7/hnnQuI8p7A==}
    engines: {node: '>=18.14.1', npm: '>=6.14.0'}
    hasBin: true
    dependencies

需求 #

如何解决该问题，或如何让Vite排除对node_modules的检查？

pnpm + 目录机制说明 #

node_modules/.pnpm 里带 + 的目录是 pnpm 的依赖标识方案：

• 用 + 替换依赖包名中的 /，比如 @astrojs/react 转为 @astrojs+react，避免路径分隔符冲突
• 下划线 _ 后缀是该依赖的关联环境信息，包含 peer 依赖、关联依赖版本等，用来区分不同上下文安装的同版本依赖，保障依赖隔离和复用。

Vite 分析 node_modules 的原因 #

正常情况下 Vite 不会处理 node_modules 文件，触发该问题的常见原因：

1. 依赖包提供未编译的源码（如 ESNext、JSX 语法）
2. 配置错误将 node_modules 加入了 Vite 的处理列表
3. 插件（如 @vitejs/plugin-react）对特定依赖进行转换
4. 依赖路径解析异常，导致 Vite 误将 node_modules 文件当作项目源码

解决步骤 #

1. 配置 Vite 排除 node_modules #

在项目根目录的 astro.config.mjs 中添加 Vite 配置，明确排除 node_modules：

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [react(), tailwind()],
  vite: {
    optimizeDeps: {
      exclude: ['/node_modules/**/*']
    },
    esbuild: {
      exclude: ['/node_modules/**/*']
    },
    server: {
      fs: {
        // monorepo 环境下允许访问上级目录，但避免误处理 node_modules
        allow: ['../..'],
        // 明确禁止访问 node_modules 目录
        deny: ['/node_modules/**/*']
      }
    }
  }
});

2. 清理缓存并重装依赖 #

pnpm 缓存损坏可能导致依赖异常，执行：

pnpm store prune
pnpm install --force

3. 检查 monorepo 配置 #

确保根目录的 .npmrc 或 pnpm-workspace.yaml 无异常：

• 不要启用 shamefully-hoist，该选项会破坏 pnpm 的依赖隔离
• 检查 public-hoist-pattern，避免将 vite、astro 等核心依赖错误提升到根 node_modules

4. 对比正常项目的依赖差异 #

同仓库中 Preact 项目正常，可对比两者：

• package.json 中的依赖版本（重点看 astro、vite、react 插件）
• pnpm-lock.yaml 的依赖树，排查版本冲突
• Vite/Astro 配置文件，看是否有插件或规则差异

5. 调整依赖版本 #

如果是版本兼容性问题：

• 同步 astro、vite 版本到和 Preact 项目一致
• 确保 @vitejs/plugin-react 版本与 vite 版本匹配（参考 peerDependencies 要求）

内容的提问来源于stack exchange，提问作者Nikola-Milovic