Kako popraviti napako Module Not Found: Can’t Resolve fs v Webpacku

Zadnja preverba: 11. september 2026. Napaka “Module not found: Error: Can’t resolve 'fs'” običajno pomeni, da Webpack gradi kodo za brskalnik, vendar vaša izvorna koda – ali ena od njenih odvisnosti – uvaža modul datotečnega sistema Node.js. Dokumentacija Node.js navaja node:fs kot API za interakcijo z datotečnim sistemom, medtem ko trenutna dokumentacija Webpacka pravi, da Webpack 5 ne polifilira več samodejno jedrnih modulov Node.js za gradnje v brskalniku.

Pomembno je izbrati popravek, ki ustreza temu, kaj koda dejansko poskuša storiti. Ne obstaja ena sama nastavitev, ki bi bila pravilna za vsak projekt. Če vaša aplikacija res potrebuje branje datotek z diska strežnika, premaknite to delo v kodo Node/strežnika. Če odvisnost uvaža fs samo za neobvezno funkcijo, ki je namenjena izključno Node.js in je vaša zbirka za brskalnik nikoli ne uporablja, je lahko resolve.fallback: { fs: false } ustrezna rešitev. Če ima paket združljivo različico za brskalnik, uporabite to. In če je zbirka namenjena izvajanju v okolju Node, ciljno okolje nastavite na Node, namesto da se pretvarjate, da gre za spletno zbirko.

Hitra tabela odločitev

Uradna dokumentacija resolve.fallback Webpacka navaja, da Webpack 5 ne polifilira več samodejno jedrnih modulov Node. Njegove opombe ob izdaji Webpacka 5 pojasnjujejo razlog: samodejni polifili so lahko dodali veliko nepotrebne združljivostne kode v zbirke za frontend, zato je Webpack prenesel odgovornost na avtorja aplikacije ali paketa.

Korak 1: Ugotovite, kdo uvaža fs

Začnite s prvo uporabno vrstico v izhodu napake Webpacka. Običajno kaže na datoteko, kjer je razrešitev spodletela, na primer:

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

Če je spodletela datoteka vaša, jo poiščite za eno od oblik:

const fs = require('fs')

// ali
import fs from 'node:fs'

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

Uradna dokumentacija datotečnega sistema Node.js potrjuje, da sta node:fs in node:fs/promises API-ja Node.js za operacije z datotečnim sistemom. Navadna zbirka za brskalnik ne pridobi dostopa do diska strežnika samo zato, ker Webpack lahko razčleni uvoz.

Če je spodletela datoteka pod node_modules, ne urejajte takoj tega paketa na mestu. Najprej identificirajte, katera vrhnja odvisnost ga je prinesla v vašo zbirko za brskalnik. Uporabno vprašanje ni le “Kateri paket uvaža fs?” ampak “Zakaj je ta pot kode, usmerjena v Node, dosegljiva iz mojega vnosa za odjemalca?”

Uporabite to diagnozo, ko: se napaka pojavi po nadgradnji Webpacka, dodajanju odvisnosti, uvozu prejšnje samo-strežniškega pripomočka v kodo frontend-a ali premikanju skupne kode v zbirko za odjemalca.

Praktična preverba: začasno odstranite uvoz, ki vodi do spodletelega modula, in ponovno zgradite. Če napaka fs izgine, ste potrdili pot odvisnosti pred spremembo konfiguracije Webpacka.

Korak 2: Če koda res potrebuje dostop do datotečnega sistema, jo premaknite v kodo Node/strežnika

To je najboljši popravek, ko koda potrebuje branje konfiguracijskih datotek, predlog, lokalnih dokumentov, zasebnih ključev, generiranih virov, strežniških dnevnikov ali česa drugega z datotečnega sistema stroja.

Na primer, to je ustrezno v okolju Node:

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

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

Vendar tega ne bi smeli vleči v vnos za brskalnik. Namesto tega izpostavite rezultat prek strežniške plasti vaše aplikacije. Poenostavljena razdelitev je lahko:

// koda na strani strežnika
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)
})

// koda na strani brskalnika
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 arhitekturni: dodate strežniško končno točko ali drugo strežniško mejo, vendar ohranite semantiko fs. Brskalnik zahteva podatke; strežnik bere datotečni sistem.

Ta rešitev je ustrezna, ko: je operacija z datotečnim sistemom resnična in potrebna.

Ta rešitev ni potrebna, ko: uvoz obstaja samo znotraj neobvezne poti kode Node, ki je brskalnik nikoli ne izvede. V tem primeru je lahko vnos paketa, specifičen za brskalnik, ali ignoriran nadomestni način (fallback) čistejši.

Korak 3: Uporabite resolve.fallback: { fs: false } samo, če je obnašanje datotečnega sistema neobvezno

Uradni vodnik Webpacka za migracijo iz različice 4 v 5 izrecno navaja, da bi morale konfiguracije, ki uporabljajo staro vzorec node.fs: 'empty', preiti na:

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

Glejte uradni vodnik za migracijo Webpacka 5.

Nastavitev nadomestnega načina na false pove Webpacku, naj ne vključi implementacije za ta nerazrešen modul. To je lahko povsem pravilno za paket, ki vsebuje zaščiteno vejo, namenjeno samo Node.js, kot je koda, ki uporablja fs samo med strežniškim upodabljanjem (SSR) ali izvajanjem CLI.

Lahko pa skrije napako pri gradnji in vam pusti napako pri zasnovi v času izvajanja. Razmislite o tej odvisnosti:

const fs = require('fs')

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

Če vaš brskalnik dejansko kliče loadUserConfig(), zamenjava fs z “nič” ne ustvari delujočega datotečnega sistema brskalnika. Gradnja se lahko nadaljuje, vendar funkcija še vedno ne more izvesti namenjene operacije Node.

Uporabite fs: false, ko: ste preverili, da veja, specifična za datotečni sistem, ni uporabljena v cilju za splet.

Ne uporabljajte je, ko: vaša funkcija v brskalniku je odvisna od readFileSync, prehajanja po imenikih, strežniških poti ali drugega resničnega obnašanja datotečnega sistema Node.

Zakaj je “samo namestite polifil za fs” običajno napačen prvi odgovor

Trenutna dokumentacija resolve.fallback Webpacka navaja primere ročnih polifilov za več jedrnih modulov Node, kot so path, buffer, stream in crypto. Pomembno je, da njegov seznam združljivosti ne zagotavlja splošne zamenjave za fs, ki bi bila enakovredna datotečnemu sistemu Node.

Ta razlika je pomembna. Pripomočke JavaScript je pogosto mogoče reproducirati v brskalniku. Poljuben dostop do datotečnega sistema gostitelja/strežnika je zmožnost izvajalnega okolja, ne le manjkajoča pomožna funkcija.

Če res potrebujete tok dela v brskalniku, izberite zasnovo, ki je nativna za brskalnik, za specifično nalogo – na primer, pridobite vir z URL-ja, uporabite izbiro datoteke ali shranite podatke aplikacije z ustrezno mehanizmom shranjevanja brskalnika. Ne ocenjujte uspeha samo na podlagi tega, ali Webpack neha prikazovati napako.

Možnost 4: Raje uporabite odvisnost ali izvoz paketa, združljiv z brskalnikom

Če napaka izvira iz paketa tretje osebe, preverite, ali ta paket uradno podpira brskalnike. Trenutni vodnik za exports paketa Webpacka pojasnjuje, da lahko paketi zagotavljajo pogojne izvoze za okolja, kot sta browser in node. Smernice ob izdaji Webpacka tudi priporočajo, da avtorji paketov zagotovijo alternative, združljive s frontendom, kadar so implementacije, namenjene samo Node.js, neprimerne za brskalnike.

Na primer, paket lahko konceptualno izpostavi:

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

Če nadgrajena različica paketa zagotavlja pravilen vnos za brskalnik, vaša starejša različica pa ne, je nadgradnja lahko varnejša kot konfiguracija fs: false. Prav tako lahko zamenjava paketa, usmerjenega v Node, s paketom, ki je izrecno zasnovan za uporabo v brskalniku, zmanjša hacke združljivosti in kompleksnost zbirke.

Izberite to pot, ko: odvisnost naj bi delovala v brskalnikih, vendar nameščena različica izbere ali izpostavi implementacijo, namenjeno samo Node.js.

Kompromis: nadgradnja ali zamenjava paketa lahko uvede spremembe API-ja, zato zaženite običajne teste aplikacije in ne obravnavajte uspešne kompilacije kot zadostne.

Možnost 5: Če je izhod zbirka Node, nastavite cilj na Node

Včasih Webpack sploh ne proizvaja kode za brskalnik. Morda gradite CLI, ozadnega delavca, gradbeno orodje, strežnik SSR ali storitev Node. V tem primeru je poskus zatiranja fs napačen: izvajalno okolje ga dejansko zagotavlja.

Uradna dokumentacija o ciljih (Targets) Webpacka pravi, da:

module.exports = {
  target: 'node'
}

prevaja za okolje, podobno Node.js, in pusti vgrajene module, kot sta fs in path, da jih Node zagotovi v času izvajanja.

Podrobnejša referenca za konfiguracijo cilja Webpacka tudi razlikuje med web, node, cilji Electron, spletnimi delavci in drugimi okolji.

Uporabite target: 'node', ko: bo nastali JavaScript izveden pod Node.js.

Ne uporabljajte ga za “popravek” običajne SPA za brskalnik: sprememba cilja ne naredi brskalnika nenadoma zagotavljajočega API-je datotečnega sistema Node. Spremeni okolje, za katerega Webpack predpostavlja, da bo izvedlo zbirko.

Napredne gradnje Node: zunanji moduli (externals) lahko ohranijo vgrajene module v času izvajanja

Za strežniške zbirke Webpack zagotavlja tudi obnašanje zunanjih modulov, usmerjeno v Node. Njegova uradna dokumentacija o zunanjih modulih (Externals) navaja, da lahko externalsPresets.node obravnava vgrajene module Node, kot so fs, path in vm, kot zunanje in jih naloži z require() izvajalnega okolja Node.

Tipična konfiguracija, usmerjena v Node, je zato lahko videti takole:

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

To je napredna skrb za strežniško zbirko, ne zaobid za brskalnik.

Korak 4: Ponovno zgradite, nato preizkusite funkcijo, ki je povzročila uvoz

Po arhitekturni ali konfiguracijski spremembi ponovno zgradite:

npm run build

Čista kompilacija dokazuje le, da je razrešitev modulov uspela. Ne dokazuje, da se prizadeta funkcija obnaša pravilno. Preizkusite glede na izbrani popravek:

• Če ste premaknili dostop do datotek na strežnik, pokličite funkcijo v brskalniku in preverite, ali strežniška končna točka vrne pričakovane podatke.
• Če ste nastavili fs: false, izvedite odvisnost v brskalniku in potrdite, da nikoli ne vstopi v vejo, odvisno od datotečnega sistema.
• Če ste preklopili na gradnjo paketa za brskalnik, zaženite resničen uporabniški tok dela paketa.
• Če ste spremenili cilj na Node, izvedite zgrajen izhod pod različico Node, ki jo podpirate.

Primerjava pogostih popravkov

Poseben primer: skupna koda, ki jo uvažajo tako zbirke za brskalnik kot za strežnik

Pogost vir te napake je modul pripomočka, ki vsebuje tako čiste funkcije kot pripomočke, namenjene samo Node.js:

// 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')
}

Tudi če vaš brskalnik uvaža samo formatDate, lahko uvoz fs na vrhu prisili Webpack, da razreši fs. Čistejša zasnova je razdelitev modulov:

// 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 naredi mejo izvajalnega okolja vidno v grafu modulov namesto zanašanja na tree-shaking ali nadomestni način za odstranitev nezdružljivega uvoza.

Poseben primer: napaka se je pojavila po nadgradnji iz Webpacka 4

To je eden klasičnih simptomov migracije na Webpack 5. Webpack 4 je samodejno zagotavljal kompatibilnostne podlage (shims) za mnoge jedrne module Node. Webpack 5 je to namenoma prenehal početi. Če je vaša koda “delovala pred nadgradnjo”, se vprašajte, ali je res potrebovala funkcijo Node v brskalniku ali ali je star bundler tiho vbrizgal združljivostno kodo.

Uradni vodnik za migracijo Webpacka priporoča branje navodil za prelomne spremembe v napaki gradnje in zamenjavo stare združljivostne konfiguracije node.* z novejšim pristopom razreševalca, kjer je to ustrezno.

Ne predpostavljajte, da je ponovno ustvarjanje vsakega polifila Webpacka 4 najboljša migracija. Lastne opombe ob izdaji Webpacka priporočajo module, združljive s frontendom, kjer je to mogoče.

Končni samopregled

Pred zaključkom problema preverite te točke:

1. Najdete točno izvorno datoteko ali odvisnost, ki uvaža fs.
2. Potrdite, ali prizadeta zbirka teče v brskalniku ali v okolju Node.
3. Če gre za zbirko za brskalnik, preverite, ali funkcija res potrebuje obnašanje datotečnega sistema.
4. Če ga potrebuje, premaknite operacijo z datotečnim sistemom za strežniško mejo.
5. Če je uporaba fs v odvisnosti neobvezna in nikoli izvedena v brskalniku, razmislite o resolve.fallback: { fs: false }.
6. Če paket uradno zagotavlja izvoz za brskalnik, raje uporabite to kot zatiranje zahtevanega obnašanja.
7. Če zbirka teče v okolju Node, uporabite cilj Node namesto spletnega cilja.
8. Ponovno zgradite in potrdite, da je napaka pri razrešitvi modulov izginila.
9. Zaženite dejansko funkcijo, ki je prej povlekla fs; ne ustavite se pri “uspešno prevedeno”.

Trajna rešitev je uskladitev kode z njenim izvajalnim okoljem. fs pripada okolju datotečnega sistema Node. Webpack 5 naredi to mejo bolj vidno, ker ne vbrizguje več samodejno polifilov jedra Node. Ko se enkrat odločite, ali delo z datotečnim sistemom pripada strežniku, je neobvezno v brskalniku ali je del zbirke, usmerjene v Node, postane pravilna konfiguracija veliko lažje izbrana.