Ako opraviť chybu „Module not found: Can’t resolve fs“ vo Webpacku

Naposledy overené: 11. septembra 2026. Chyba „Module not found: Error: Can’t resolve 'fs'“ zvyčajne znamená, že Webpack zostavuje kód pre prehliadač, ale váš zdrojový kód – alebo jedna z jeho závislostí – importuje modul súborového systému Node.js. Dokumentácia Node.js uvádza node:fs ako API pre interakciu so súborovým systémom, zatiaľ čo aktuálna dokumentácia Webpacku uvádza, že Webpack 5 už automaticky nepolyfilluje core moduly Node.js pre zostavy pre prehliadač.

Dôležité je vybrať opravu, ktorá zodpovedá tomu, čo sa kód skutočne snaží urobiť. Neexistuje jedno nastavenie, ktoré by bolo správne pre každý projekt. Ak vaša aplikácia skutočne potrebuje čítať súbory z disku servera, presuňte túto prácu do kódu Node/server. Ak závislosť importuje fs len pre voliteľnú funkciu špecifickú pre Node, ktorá sa vo vašom bundle pre prehliadač nikdy nepoužíva, môže byť vhodné použiť resolve.fallback: { fs: false }. Ak balík má zostavu kompatibilnú s prehliadačom, použite tú. A ak je bundle určený na beh v prostredí Node, nastavte cieľ na Node namiesto toho, aby ste predstierali, že ide o webový bundle.

Rýchla rozhodovacia tabuľka

Oficiálna dokumentácia resolve.fallback Webpacku uvádza, že Webpack 5 už automaticky nepolyfilluje core moduly Node.js. Jeho poznámky k vydaniu Webpack 5 vysvetľujú dôvod: automatické polyfilly mohli pridávať veľký, zbytočný kompatibilný kód do frontendových bundleov, takže Webpack presunul zodpovednosť na autora aplikácie alebo balíka.

Krok 1: Zistite, kto importuje fs

Začnite prvým užitočným riadkom vo výstupe chyby Webpacku. Zvyčajne ukazuje na súbor, kde zlyhalo riešenie, napríklad:

ERROR in ./src/utils/fileHelper.js 1:0-20
Module not found: Error: Can't resolve 'fs'

Ak je zlyhávajúci súbor váš, vyhľadajte v ňom jeden z týchto tvarov:

const fs = require('fs')

// alebo
import fs from 'node:fs'

// alebo
import { readFile } from 'node:fs/promises'

Oficiálna dokumentácia súborového systému Node.js potvrdzuje, že node:fs a node:fs/promises sú API Node.js pre operácie so súborovým systémom. Bežný bundle pre prehliadač nezíska prístup k disku servera len preto, že Webpack dokáže parsovať import.

Ak je zlyhávajúci súbor pod node_modules, neupravujte okamžite tento balík na mieste. Najprv identifikujte, ktorá top-level závislosť ho dostala do vášho bundle pre prehliadač. Užitočná otázka nie je len „Ktorý balík importuje fs?“, ale „Prečo je táto cesta kódu orientovaná na Node dosiahnuteľná z môjho klientskeho vstupu?“

Použite túto diagnostiku, keď: chyba sa objaví po upgradovaní Webpacku, pridaní závislosti, importe predtým server-only utility do frontendového kódu alebo presunutí zdieľaného kódu do klientskeho bundle.

Praktická kontrola: dočasne odstráňte import, ktorý vedie k zlyhávajúcemu modulu, a znova zostavte projekt. Ak chyba fs zmizne, potvrdili ste cestu závislosti pred zmenou konfigurácie Webpacku.

Krok 2: Ak kód skutočne potrebuje prístup k súborovému systému, presuňte ho do kódu Node/server

Toto je najlepšia oprava, keď kód potrebuje čítať konfiguračné súbory, šablóny, lokálne dokumenty, súkromné kľúče, generované assety, serverové logy alebo čokoľvek iné zo súborového systému stroja.

Napríklad, toto je vhodné v Node:

import { readFile } from 'node:fs/promises'

export async function loadTemplate() {
  return readFile('./templates/email.html', 'utf8')
}

Mal by sa však dostať do vstupu pre prehliadač. Namiesto toho vystavte výsledok cez serverovú vrstvu vašej aplikácie. Zjednodušené rozdelenie môže vyzerať takto:

// server-side code
import { readFile } from 'node:fs/promises'

app.get('/api/template', async (req, res) => {
  const text = await readFile('./templates/email.html', 'utf8')
  res.type('text/plain').send(text)
})

// browser-side code
export async function loadTemplate() {
  const response = await fetch('/api/template')
  if (!response.ok) throw new Error('Failed to load template')
  return response.text()
}

Kompromis je architektonický: pridáte serverový endpoint alebo inú serverovú hranicu, ale zachováte sémantiku fs. Prehliadač požaduje dáta; server číta súborový systém.

Toto riešenie je vhodné, keď: operácia so súborovým systémom je reálna a nevyhnutná.

Toto riešenie nie je nevyhnutné, keď: import existuje len vnútri voliteľnej cesty kódu pre Node, ktorú prehliadač nikdy nevykoná. V takom prípade môže byť čistejšie použiť špecifický vstup balíka pre prehliadač alebo ignorovaný fallback.

Krok 3: Použite resolve.fallback: { fs: false } len ak je správanie súborového systému voliteľné

Oficiálna migračná príručka Webpacku z verzie 4 na 5 konkrétne uvádza, že konfigurácie používajúce starý vzor node.fs: 'empty' by sa mali presunúť na:

module.exports = {
  // ...
  resolve: {
    fallback: {
      fs: false
    }
  }
}

Pozrite si oficiálnu migračnú príručku Webpack 5.

Nastavenie fallbacku na false hovorí Webpacku, aby nezaradil implementáciu pre tento nevyriešený modul. To môže byť presne správne pre balík, ktorý obsahuje chránenú vetvu špecifickú pre Node, napríklad kód, ktorý používa fs len počas server-side renderingu alebo spustenia CLI.

Môže to tiež skryť chybu zostavy a nechať vás s chybou v návrhu runtime. Uvažujte o tejto závislosti:

const fs = require('fs')

export function loadUserConfig(path) {
  return fs.readFileSync(path, 'utf8')
}

Ak váš prehliadač skutočne volá loadUserConfig(), nahradenie fs „ničím“ nevytvorí funkčný súborový systém prehliadača. Zostava môže pokračovať, ale funkcia stále nemôže vykonať zamýšľanú operáciu Node.

Použite fs: false, keď: overili ste, že vetva špecifická pre súborový systém sa nepoužíva v cieľovom prostredí web.

Nepoužívajte ho, keď: vaša funkcia v prehliadači závisí od readFileSync, prechádzania adresármi, serverových ciest alebo iného reálneho správania súborového systému Node.

Prečo „len nainštalujte polyfill fs“ je zvyčajne nesprávna prvá odpoveď

Aktuálna dokumentácia resolve.fallback Webpacku uvádza príklady manuálnych polyfillov pre niekoľko core modulov Node.js, ako sú path, buffer, stream a crypto. Je pozoruhodné, že jej zoznam kompatibility neposkytuje všeobecnú náhradu za fs ekvivalentnú súborovému systému Node.

Tento rozdiel je dôležitý. Utility JavaScriptu sa často dajú reprodukovať v prehliadači. Ľubovoľný prístup k súborovému systému hostiteľa/servera je možnosťou runtime, nie len chýbajúcou pomocnou funkciou.

Ak skutočne potrebujete workflow pre prehliadač, zvoľte natívny dizajn prehliadača pre konkrétnu úlohu – napríklad načítajte asset z URL, nechajte používateľa vybrať súbor alebo uložte dáta aplikácie pomocou vhodného mechanizmu ukladania prehliadača. Nesúďte úspech len podľa toho, či Webpack prestane zobrazovať chybu.

Možnosť 4: Preferujte závislosť kompatibilnú s prehliadačom alebo export balíka

Ak chyba pochádza z balíka tretej strany, preskúmajte, či tento balík oficiálne podporuje prehliadače. Aktuálna príručka exports balíkov Webpacku vysvetľuje, že balíky môžu poskytovať podmienené exporty pre prostredia ako browser a node. Návod k vydaniu Webpacku tiež odporúča, aby autori balíkov poskytovali alternatívy kompatibilné s frontendom, keď sú implementácie špecifické pre Node nevhodné pre prehliadače.

Napríklad balík môže konceptuálne vystavovať:

{
  "exports": {
    ".": {
      "browser": "./dist/browser.js",
      "node": "./dist/node.js",
      "default": "./dist/browser.js"
    }
  }
}

Ak novšia verzia balíka poskytuje správny vstup pre prehliadač, zatiaľ čo vaša staršia verzia nie, upgrade môže byť bezpečnejší ako konfigurácia fs: false. Rovnako nahradenie balíka orientovaného na Node balíkom explicitne navrhnutým pre použitie v prehliadači môže znížiť kompatibilné hacky a zložitosť bundle.

Zvoľte túto cestu, keď: závislosť by mala fungovať v prehliadačoch, ale nainštalovaná verzia vyberá alebo vystavuje implementáciu špecifickú pre Node.

Kompromis: upgrade alebo nahradenie balíka môže zaviesť zmeny API, preto spustite bežné testy aplikácie, namiesto toho, aby ste považovali úspešnú kompiláciu za dostatočnú.

Možnosť 5: Ak je výstupom bundle pre Node, nastavte cieľ na Node

Niekedy Webpack vôbec nevytvára kód pre prehliadač. Môžete bundlovať CLI, background worker, build tool, SSR server alebo Node service. V takom prípade sa snažiť potlačiť fs je späť: runtime ho skutočne poskytuje.

Oficiálna dokumentácia Targets Webpacku uvádza, že:

module.exports = {
  target: 'node'
}

sa kompiluje pre prostredie podobné Node.js a necháva vstavané moduly, ako sú fs a path, na Node, aby ich poskytol v runtime.

Podrobnejšia referencia konfigurácie target Webpacku tiež rozlišuje web, node, ciele pre Electron, web workers a iné prostredia.

Použite target: 'node', keď: výsledný JavaScript bude vykonávaný pod Node.

Nepoužívajte ho na „opravu“ bežnej SPA pre prehliadač: zmena cieľa nespraví z prehliadača zrazu poskytovateľa API súborového systému Node. Mení to, aké prostredie Webpack predpokladá, že bude vykonávať bundle.

Pokročilé zostavy pre Node: externals môžu ponechať vstavané moduly v runtime

Pre serverové bundle Webpack tiež poskytuje správanie externals orientované na Node. Jeho oficiálna dokumentácia Externals uvádza, že externalsPresets.node môže považovať vstavané moduly Node, ako sú fs, path a vm, za externé a načítať ich pomocou runtime require() Node.

Typická konfigurácia orientovaná na Node by preto mohla vyzerať takto:

module.exports = {
  target: 'node',
  externalsPresets: {
    node: true
  }
}

Toto je pokročilá záležitosť serverového bundle, nie workaround pre prehliadač.

Krok 4: Znovu zostavte, potom otestujte funkciu, ktorá spôsobila import

Po vykonaní architektonickej alebo konfiguračnej zmeny znova zostavte projekt:

npm run build

Čistá kompilácia dokazuje len to, že riešenie modulov uspelo. Nedokazuje, že postihnutá funkcia sa správa správne. Testujte podľa zvolenej opravy:

• Ak ste presunuli prístup k súborom na server, zavolajte funkciu v prehliadači a overte, či serverový endpoint vracia očakávané dáta.
• Ak ste nastavili fs: false, precvičte závislosť v prehliadači a potvrďte, že nikdy nevstúpi do vetvy závislej od súborového systému.
• Ak ste prešli na zostavu balíka pre prehliadač, spustite skutočný workflow balíka orientovaný na používateľa.
• Ak ste zmenili cieľ na Node, vykonajte zostavený výstup pod verziou Node, ktorú podporujete.

Porovnanie bežných opráv

Špeciálny prípad: zdieľaný kód importovaný bundlemi pre prehliadač aj server

Častým zdrojom tejto chyby je utilitný modul, ktorý obsahuje čisté funkcie aj pomocné funkcie špecifické pre Node:

// shared-utils.js
import fs from 'node:fs'

export function formatDate(date) {
  return new Intl.DateTimeFormat('en-US').format(date)
}

export function readConfig(path) {
  return fs.readFileSync(path, 'utf8')
}

Aj keď váš prehliadač importuje len formatDate, top-level import fs môže prinútiť Webpack riešiť fs. Čistejší dizajn je rozdeliť moduly:

// shared/formatDate.js
export function formatDate(date) {
  return new Intl.DateTimeFormat('en-US').format(date)
}

// server/readConfig.js
import fs from 'node:fs'

export function readConfig(path) {
  return fs.readFileSync(path, 'utf8')
}

Toto robí hranicu runtime viditeľnou v grafe modulov namiesto spoliehania sa na tree-shaking alebo fallback na odstránenie nekompatibilného importu.

Špeciálny prípad: chyba sa objavila po upgrade z Webpack 4

Toto je jeden z klasických symptómov migrácie na Webpack 5. Webpack 4 automaticky dodával kompatibilné shims pre mnoho core modulov Node.js. Webpack 5 to zámerne prestal robiť. Ak váš kód „fungoval pred upgrade“, opýtajte sa, či skutočne potreboval funkciu Node v prehliadači, alebo či starý bundler ticho vstrekol kompatibilný kód.

Oficiálna migračná príručka Webpacku odporúča prečítať si pokyny k breaking change v chybe zostavy a nahradiť starú kompatibilnú konfiguráciu node.* novším prístupom resolvera, kde je to vhodné.

Nepredpokladajte, že znovuvytvorenie každého polyfillu Webpack 4 je najlepšia migrácia. Vlastné poznámky k vydaniu Webpacku odporúčajú moduly kompatibilné s frontendom, kde je to možné.

Finálna samo-kontrola

Pred uzavretím problému overte tieto body:

1. Nájdite presný zdrojový súbor alebo závislosť, ktorá importuje fs.
2. Potvrďte, či postihnutý bundle beží v prehliadači alebo v Node.
3. Ak je to bundle pre prehliadač, overte, či funkcia skutočne potrebuje správanie súborového systému.
4. Ak áno, presuňte operáciu so súborovým systémom za serverovú hranicu.
5. Ak je použitie fs v závislosti voliteľné a nikdy sa nevykonáva v prehliadači, zvážte resolve.fallback: { fs: false }.
6. Ak balík oficiálne poskytuje export pre prehliadač, uprednostnite to pred potlačením požadovaného správania.
7. Ak bundle vykonáva v Node, použite cieľ Node namiesto cieľa web.
8. Znovu zostavte a potvrďte, že chyba riešenia modulu je preč.
9. Spustite skutočnú funkciu, ktorá predtým ťahala fs; nezastavte sa pri „úspešne skompilované“.

Trvalá oprava spočíva v zosúladení kódu s jeho runtime prostredím. fs patrí do prostredia súborového systému Node. Webpack 5 robí túto hranicu viditeľnejšou tým, že už automaticky nevstrekuje polyfilly core modulov Node. Ako sa raz rozhodnete, či práca so súborovým systémom patrí na server, je voliteľná v prehliadači, alebo je súčasťou bundle zameraného na Node, správna konfigurácia sa stane oveľa ľahšie voliteľnou.