Jak opravit chybu Module Not Found: Nelze vyřešit fs ve Webpacku

Naposledy ověřeno: 11. září 2026. Chyba „Module not found: Error: Can’t resolve 'fs'“ obvykle znamená, že Webpack sestavuje kód pro prohlížeč, ale váš zdrojový kód – nebo jedna z jeho závislostí – importuje modul souborového systému Node.js. Dokumentace Node popisuje node:fs jako API pro interakci se souborovým systémem, zatímco aktuální dokumentace Webpacku uvádí, že Webpack 5 již automaticky nepolyfilluje jádrové moduly Node.js pro sestavení v prohlížeči.

Důležité je vybrat opravu, která odpovídá tomu, co se kód skutečně snaží dělat. Neexistuje jediné nastavení, které by bylo správné pro každý projekt. Pokud vaše aplikace skutečně potřebuje číst soubory z disku serveru, přesuňte tuto práci do kódu Node/server. Pokud závislost importuje fs pouze pro volitelnou funkci dostupnou jen v Node, kterou váš balíček pro prohlížeč nikdy nepoužívá, může být vhodné nastavení resolve.fallback: { fs: false }. Pokud balíček nabízí kompatibilní sestavení pro prohlížeč, použijte to. A pokud je balíček určen ke spuštění v Node, cílte na Node místo předstírání, že jde o webový balíček.

Rychlá rozhodovací tabulka

Oficiální dokumentace resolve.fallback Webpacku uvádí, že Webpack 5 již automaticky nepolyfilluje jádrové moduly Node. Jeho poznámky k vydání Webpack 5 vysvětlují důvod: automatické polyfilly mohly přidat velký, zbytečný kompatibilní kód do balíčků pro frontend, takže Webpack přesunul odpovědnost na autora aplikace nebo balíčku.

Krok 1: Zjistěte, kdo importuje fs

Začněte prvním užitečným řádkem ve výstupu chyby Webpacku. Obvykle ukazuje na soubor, kde došlo k selhání řešení, například:

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

Pokud je selhávající soubor váš, prohledejte ho pro obě formy:

const fs = require('fs')

// nebo
import fs from 'node:fs'

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

Oficiální dokumentace File System Node potvrzuje, že node:fs a node:fs/promises jsou API Node pro operace se souborovým systémem. Běžný balíček pro prohlížeč nezíská přístup k disku serveru jen proto, že Webpack dokáže import parsovat.

Pokud je selhávající soubor pod node_modules, neupravujte okamžitě tento balíček na místě. Nejprve identifikujte, která závislost nejvyšší úrovně ho přivedla do vašeho balíčku pro prohlížeč. Užitečná otázka není jen „Který balíček importuje fs?“, ale „Proč je tato cesta kódu orientovaná na Node dosažitelná z mého klientského vstupu?“

Použijte tuto diagnostiku, když: chyba se objeví po aktualizaci Webpacku, přidání závislosti, importu dříve pouze serverové utility do kódu frontendu nebo přesunu sdíleného kódu do klientského balíčku.

Praktická kontrola: dočasně odstraňte import, který vede k selhávajícímu modulu, a znovu sestavte. Pokud chyba fs zmizí, potvrdili jste cestu závislosti před změnou konfigurace Webpacku.

Krok 2: Pokud kód skutečně potřebuje přístup k souborovému systému, přesuňte ho do kódu Node/server

Toto je nejlepší oprava, když kód potřebuje číst konfigurační soubory, šablony, lokální dokumenty, soukromé klíče, generované assety, serverové logy nebo cokoli jiného ze souborového systému stroje.

Například toto je vhodné v Node:

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

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

Do vstupu pro prohlížeč by to však nemělo být taháno. Místo toho vystavte výsledek prostřednictvím serverové vrstvy vaší aplikace. Zjednodušené rozdělení by mohlo vypadat 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ý: přidáte serverový endpoint nebo jinou serverovou hranici, ale zachováte sémantiku fs. Prohlížeč požaduje data; server čte souborový systém.

Toto řešení je vhodné, když: operace se souborovým systémem je reálná a nutná.

Toto řešení není nutné, když: import existuje pouze uvnitř volitelné cesty kódu pro Node, kterou prohlížeč nikdy nespustí. V takovém případě může být čistší vstup balíčku specifický pro prohlížeč nebo ignorovaný fallback.

Krok 3: Použijte resolve.fallback: { fs: false } pouze tehdy, když je chování souborového systému volitelné

Oficiální migrační příručka Webpacku z verze 4 na 5 specificky uvádí, že konfigurace používající starý vzor node.fs: 'empty' by měly přejít na:

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

Viz oficiální migrační příručka Webpack 5.

Nastavení fallbacku na false říká Webpacku, aby nezačlenil implementaci pro tento nevyřešený modul. To může být přesně správné pro balíček, který obsahuje chráněnou větev pouze pro Node, například kód, který používá fs pouze během serverového vykreslování nebo spuštění CLI.

Může to také skrýt chybu sestavení a nechat vás s chybou v návrhu za běhu. Zvažte tuto závislost:

const fs = require('fs')

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

Pokud váš prohlížeč skutečně volá loadUserConfig(), nahrazení fs „ničím“ nevytvoří funkční souborový systém prohlížeče. Sestavení může pokračovat, ale funkce stále nemůže provést zamýšlenou operaci Node.

Použijte fs: false, když: jste ověřili, že větev specifická pro souborový systém se v cíli pro web nepoužívá.

Nepoužívejte ho, když: vaše funkce v prohlížeči závisí na readFileSync, procházení adresářů, serverových cestách nebo jiném reálném chování souborového systému Node.

Proč „prostě nainstalujte polyfill fs“ je obvykle špatná první odpověď

Aktuální dokumentace resolve.fallback Webpacku uvádí příklady ručních polyfillů pro několik jádrových modulů Node, jako jsou path, buffer, stream a crypto. Je pozoruhodné, že její seznam kompatibility neposkytuje obecnou náhradu za fs ekvivalentní souborovému systému Node.

Tento rozdíl je důležitý. Utility JavaScriptu lze často reprodukovat v prohlížeči. Libovolný přístup k souborovému systému hostitele/serveru je schopnost běhového prostředí, nikoli jen chybějící pomocná funkce.

Pokud skutečně potřebujete pracovní postup v prohlížeči, zvolte nativní návrh prohlížeče pro konkrétní úkol – například načtěte asset z URL, nechte uživatele vybrat soubor nebo uložte data aplikace pomocí vhodného mechanismu úložiště prohlížeče. Nesuďte úspěch pouze podle toho, zda Webpack přestane zobrazovat chybu.

Možnost 4: Preferujte závislost kompatibilní s prohlížečem nebo export balíčku

Pokud chyba pochází ze balíčku třetí strany, zkontrolujte, zda tento balíček oficiálně podporuje prohlížeče. Aktuální průvodce exports balíčků Webpacku vysvětluje, že balíčky mohou poskytovat podmíněné exporty pro prostředí jako browser a node. Doporučení k vydání Webpacku také doporučuje autorům balíčků poskytovat alternativy kompatibilní s frontendem, když jsou implementace pouze pro Node nevhodné pro prohlížeče.

Například balíček může konceptuálně vystavovat:

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

Pokud aktualizovaná verze balíčku poskytuje správný vstup pro prohlížeč, zatímco vaše starší verze ne, aktualizace může být bezpečnější než konfigurace fs: false. Stejně tak nahrazení balíčku orientovaného na Node balíčkem explicitně navrženým pro použití v prohlížeči může snížit kompatibilní hacky a složitost balíčku.

Zvolte tuto cestu, když: závislost by měla fungovat v prohlížečích, ale nainstalovaná verze vybírá nebo vystavuje implementaci pouze pro Node.

Kompromis: aktualizace nebo nahrazení balíčku může zavést změny API, takže spusťte běžné testy aplikace, místo abyste považovali úspěšné zkompilování za dostatečné.

Možnost 5: Pokud je výstupem balíček Node, nastavte cíl na Node

Někdy Webpack vůbec nevytváří kód pro prohlížeč. Můžete balíčkovat CLI, background worker, build tool, SSR server nebo službu Node. V takovém případě je snaha potlačit fs zpátečnická: běhové prostředí ho skutečně poskytuje.

Oficiální dokumentace Targets Webpacku uvádí, že:

module.exports = {
  target: 'node'
}

sestavuje pro prostředí podobné Node.js a ponechává vestavěné moduly, jako jsou fs a path, na Node, aby je poskytl za běhu.

Podrobnější reference konfigurace target Webpacku také rozlišuje web, node, cíle Electron, web workers a další prostředí.

Použijte target: 'node', když: výsledný JavaScript bude spuštěn pod Node.

Nepoužívejte ho k „opravě“ běžné SPA v prohlížeči: změna cíle neznamená, že by prohlížeč najednou poskytl API souborového systému Node. Mění to prostředí, o kterém Webpack předpokládá, že bude balíček spouštět.

Pokročilá sestavení Node: externals mohou ponechat vestavěné funkce za běhu

Pro serverové balíčky Webpack také poskytuje chování externals orientované na Node. Jeho oficiální dokumentace Externals uvádí, že externalsPresets.node může zacházet s vestavěnými funkcemi Node, jako jsou fs, path a vm, jako s externími a načítat je pomocí běhového require() Node.

Typická konfigurace orientovaná na Node by tedy mohla vypadat takto:

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

Toto je pokročilá záležitost serverového balíčku, nikoli workaround pro prohlížeč.

Krok 4: Znovu sestavte a poté otestujte funkci, která způsobila import

Po provedení architektonické nebo konfigurační změny znovu sestavte:

npm run build

Čisté zkompilování dokazuje pouze to, že řešení modulů bylo úspěšné. Nedokazuje, že se dotčená funkce chová správně. Testujte podle zvolené opravy:

• Pokud jste přesunuli přístup k souborům na server, zavolejte funkci prohlížeče a ověřte, že serverový endpoint vrací očekávaná data.
• Pokud jste nastavili fs: false, vyzkoušejte závislost v prohlížeči a potvrďte, že nikdy nevstoupí do větve závislé na souborovém systému.
• Pokud jste přešli na sestavení balíčku pro prohlížeč, spusťte skutečný uživatelský workflow balíčku.
• Pokud jste změnili cíl na Node, spusťte sestavený výstup pod verzí Node, kterou podporujete.

Srovnání běžných oprav

Speciální případ: sdílený kód importovaný balíčky pro prohlížeč i server

Častým zdrojem této chyby je utilitní modul, který obsahuje jak čisté funkce, tak pomocné funkce pouze pro 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')
}

I když váš prohlížeč importuje pouze formatDate, import fs na horní úrovni může donutit Webpack vyřešit fs. Čistší návrh je rozdělit 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')
}

To činí hranici běhového prostředí viditelnou v grafu modulů místo spoléhání se na tree-shaking nebo fallback k odstranění nekompatibilního importu.

Speciální případ: chyba se objevila po aktualizaci z Webpack 4

Toto je jeden z klasických příznaků migrace na Webpack 5. Webpack 4 automaticky dodával kompatibilní shims pro mnoho jádrových modulů Node. Webpack 5 to záměrně přestal dělat. Pokud váš kód „fungoval před aktualizací“, zeptejte se, zda skutečně potřeboval funkci Node v prohlížeči, nebo zda starý bundler tichounce vstřikoval kompatibilní kód.

Oficiální migrační příručka Webpacku doporučuje přečíst si pokyny k breaking-change ve výstupu chyby sestavení a nahradit starou kompatibilní konfiguraci node.* novějším přístupem resolveru, kde je to vhodné.

Nepředpokládejte, že recreate každého polyfillu Webpack 4 je nejlepší migrace. Vlastní poznámky k vydání Webpacku doporučují moduly kompatibilní s frontendem, kde je to možné.

Finální self-check

Před uzavřením problému ověřte tyto body:

1. Najděte přesný zdrojový soubor nebo závislost, která importuje fs.
2. Potvrďte, zda dotčený balíček běží v prohlížeči nebo v Node.
3. Pokud je to balíček pro prohlížeč, ověřte, zda funkce skutečně potřebuje chování souborového systému.
4. Pokud ano, přesuňte operaci se souborovým systémem za serverovou hranici.
5. Pokud je použití fs závislosti volitelné a nikdy se nespustí v prohlížeči, zvažte resolve.fallback: { fs: false }.
6. Pokud balíček oficiálně poskytuje export pro prohlížeč, preferujte to před potlačením požadovaného chování.
7. Pokud balíček běží v Node, použijte cíl Node místo cíle web.
8. Znovu sestavte a potvrďte, že chyba řešení modulu zmizela.
9. Spusťte skutečnou funkci, která dříve táhla fs; nezastavujte se na „zkompilováno úspěšně“.

Trvalá oprava spočívá v zarovnání kódu s jeho běhovým prostředím. fs patří do prostředí souborového systému Node. Webpack 5 činí tuto hranici viditelnější tím, že již automaticky nevstřikuje polyfilly jádra Node. Jakmile se rozhodnete, zda práce se souborovým systémem patří na server, je volitelná v prohlížeči, nebo je součástí balíčku cíleného na Node, správná konfigurace se stane mnohem snazší na výběr.