常見錯誤

找不到模組 './relative-path'

若您收到「找不到模組」的錯誤訊息，這可能代表以下幾種情況：

• 1. 您輸入的路徑有誤。請務必確認路徑是否正確。
• 2. 您可能依賴於 tsconfig.json 中的 baseUrl 設定。Vite 預設不會參考 tsconfig.json，因此若您依賴此行為，可能需要手動安裝 vite-tsconfig-paths。

import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

或者，將路徑重寫為非根目錄相對路徑：

- import helpers from 'src/helpers'
+ import helpers from '../src/helpers'

• 3. 請確認您沒有使用相對的 別名。Vite 會將這些別名視為相對於導入檔案的路徑，而非根目錄。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    alias: {
      '@/': './src/', 
      '@/': new URL('./src/', import.meta.url).pathname, 
    },
  },
});

無法模擬 "./mocked-file.js" 因為它已經載入

當對一個已被載入的模組呼叫 vi.mock 方法時，便會發生此錯誤。Vitest 拋出此錯誤是因為此呼叫無效，因為快取中的模組將會被優先使用。

請注意，vi.mock 總是會被提升（hoisted），這表示模組在測試檔案開始執行之前就已載入，最可能是在設定檔中。要修正此錯誤，請移除相關的導入語句，或在設定檔的末尾清除快取。請留意，在此情況下，設定檔與測試檔將會參考不同的模組實例。

// setupFile.js
import { vi } from 'vitest';
import { sideEffect } from './mocked-file.js';

sideEffect();

vi.resetModules();

終止 worker 失敗

當 NodeJS 的 fetch 與預設的 pool: 'threads' 一同使用時，可能會發生此錯誤。此問題已在 Timeout abort can leave process(es) running in the background #3077 中進行了相關討論。

解決方案是，您可以切換至 pool: 'forks' 或 pool: 'vmForks'。

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    pool: 'forks',
  },
});

CLI

vitest --pool=forks

記憶體區段錯誤與原生程式碼錯誤

在 pool: 'threads' 中執行 原生 NodeJS 模組 時，可能會遇到來自原生程式碼的難以理解的錯誤訊息。

• Segmentation fault (core dumped) (記憶體區段錯誤（核心已傾印）)
• thread '<unnamed>' panicked at 'assertion failed (執行緒 '<未命名>' 發生錯誤：'斷言失敗')
• Abort trap: 6 (中止陷阱：6)
• internal error: entered unreachable code (內部錯誤：進入了不可達的程式碼)

在這些情況下，原生模組可能並非為多執行緒安全而設計。解決方案是，您可以切換至 pool: 'forks'，它會在多個 node:child_process 中執行測試案例，而非 node:worker_threads。

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    pool: 'forks',
  },
});

CLI

vitest --pool=forks