Miten korjata Module Not Found: Can’t Resolve fs Webpackissä

Viimeksi varmistettu: 11. syyskuuta 2026. Virhe “Module not found: Error: Can’t resolve 'fs'” tarkoittaa yleensä, että Webpack kääntää koodia selaimelle, mutta lähdekoodissasi – tai jossakin sen riippuvuudessa – tuodaan Node.js:n tiedostojärjestelmämoduuli. Node dokumentoi node:fs:n rajapinnaksi tiedostojärjestelmän kanssa vuorovaikuttamiseen, kun taas Webpackin nykyinen dokumentaatio kertoo, että Webpack 5 ei enää automaattisesti polyfillöi Node.js:n ydinmoduuleja selainkäännöksille.

Tärkeintä on valita korjaus, joka vastaa sitä, mitä koodi todellisuudessa yrittää tehdä. Yhtä ainoaa asetusta, joka olisi oikea jokaiselle projektille, ei ole. Jos sovelluksesi todella tarvitsee tiedostojen lukemista palvelimen levyltä, siirrä tämä työ Node-/palvelinkoodiin. Jos riippuvuus tuo fs:n vain valinnaiseen Node-kohtaiseen ominaisuuteen, jota selainpaketti ei koskaan käytä, resolve.fallback: { fs: false } voi olla sopiva. Jos paketilla on selainyhteensopiva käännös, käytä sitä sen sijaan. Ja jos paketin on tarkoitus toimia Node-ympäristössä, kohdista Node sen sijaan, että teeskentelisit sen olevan web-paketti.

Nopea päätöstaulukko

Webpackin virallinen resolve.fallback-dokumentaatio toteaa, että Webpack 5 ei enää polyfillöi Node:n ydinmoduuleja automaattisesti. Sen Webpack 5 -julkaisumuistiinpanot selittävät syyn: automaattiset polyfillit saattoivat lisätä suuria, tarpeettomia yhteensopivuuskoodeja frontend-paketteihin, joten Webpack siirsi vastuun sovellukselle tai paketin tekijälle.

Vaihe 1: Selvitä, kuka tuo fs:n

Aloita Webpackin virhetulosteen ensimmäisestä hyödyllisestä rivistä. Se osoittaa yleensä tiedoston, jossa resoluutio epäonnistui, esimerkiksi:

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

Jos epäonnistuva tiedosto on sinun, etsi siitä kumpaa tahansa muotoa:

const fs = require('fs')

// tai
import fs from 'node:fs'

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

Noden virallinen File System -dokumentaatio vahvistaa, että node:fs ja node:fs/promises ovat Node-rajapintoja tiedostojärjestelmäoperaatioihin. Tavallinen selainpaketti ei saa pääsyä palvelimen levylle vain siksi, että Webpack pystyy jäsentämään tuonnin.

Jos epäonnistuva tiedosto on node_modules-hakemistossa, älä muokkaa pakettia suoraan paikallaan. Tunnista ensin, mikä ylimmän tason riippuvuus toi sen selainpakettiisi. Hyödyllinen kysymys ei ole vain “Mikä paketti tuo fs:n?”, vaan “Miksi tuo Node-kohtainen koodipolku on saavutettavissa asiakkaan entry-pisteestä?”

Käytä tätä diagnoosia, kun: virhe ilmenee Webpackin päivityksen, riippuvuuden lisäämisen, aiemmin vain palvelimelle tarkoitetun apuohjelman tuomisen frontend-koodiin tai jaetun koodin siirtämisen asiakaspakettiin jälkeen.

Käytännön tarkistus: poista väliaikaisesti tuonti, joka johtaa epäonnistuvaan moduuliin, ja käännä uudelleen. Jos fs-virhe katoaa, olet vahvistanut riippuvuuden polun ennen Webpack-konfiguraation muuttamista.

Vaihe 2: Jos koodi todella tarvitsee tiedostojärjestelmäpääsyn, siirrä se Node-/palvelinkoodiin

Tämä on paras korjaus, kun koodin on luettava konfiguraatiotiedostoja, malleja, paikallisia dokumentteja, yksityisiä avaimia, generoituja resursseja, palvelinlokeja tai mitä tahansa muuta koneen tiedostojärjestelmästä.

Esimerkiksi tämä on sopivaa Nodessa:

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

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

Se ei kuitenkaan kuulu selainentry-pisteeseen. Sen sijaan paljasta tulos sovelluksesi palvelinkerroksen kautta. Yksinkertaistettu jako voisi olla:

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

Kompromissi on arkkitehtoninen: lisäät palvelinpään tai toisen palvelinpuolen rajan, mutta säilytät fs:n merkityksen. Selain pyytää dataa; palvelin lukee tiedostojärjestelmää.

Tämä ratkaisu on sopiva, kun: tiedostojärjestelmäoperaatio on todellinen ja välttämätön.

Tämä ratkaisu ei ole tarpeen, kun: tuonti on olemassa vain valinnaisessa Node-koodipolussa, jota selain ei koskaan suorita. Tällöin selainkohtainen paketin entry-piste tai ohitettu fallback voi olla puhtaampi.

Vaihe 3: Käytä resolve.fallback: { fs: false } vain, kun tiedostojärjestelmäkäyttäytyminen on valinnaista

Webpackin virallinen Webpack 4 - 5 -migraatioopas sanoo nimenomaan, että konfiguraatioiden, jotka käyttävät vanhaa kuviota node.fs: 'empty', tulisi siirtyä muotoon:

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

Katso virallinen Webpack 5 -migraatioopas.

Fallbackin asettaminen arvoon false kertoo Webpackille, ettei sen tule sisällyttää toteutusta kyseiselle ratkaisemattomalle moduulille. Tämä voi olla täysin oikein paketille, joka sisältää suojatun Node-kohtaisen haaran, kuten koodin, joka käyttää fs:ää vain palvelinrenderöinnin tai CLI-suorituksen aikana.

Se voi myös piilottaa käännösvirheen jättäen sinut suoritusajan suunnitteluvirheen kanssa. Harkitse tätä riippuvuutta:

const fs = require('fs')

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

Jos selaimesi todella kutsuu loadUserConfig(), fs:n korvaaminen “ei millään” ei luo toimivaa selain-tiedostojärjestelmää. Käännös voi edetä, mutta ominaisuus ei silti voi suorittaa tarkoitettua Node-operaatiota.

Käytä fs: false -asetusta, kun: olet varmistanut, ettei tiedostojärjestelmäkohtaista haaraa käytetä web-kohderyhmässä.

Älä käytä sitä, kun: selainominaisuutesi riippuu readFileSync:stä, hakemistokierrosta, palvelinpoluista tai muusta todellisesta Node-tiedostojärjestelmäkäyttäytymisestä.

Miksi “vain asenna fs-polyfill” on yleensä väärä ensivastaus

Webpackin nykyinen resolve.fallback-dokumentaatio antaa esimerkkejä manuaalisista polyfilleistä useille Node:n ydinmoduuleille, kuten path, buffer, stream ja crypto. Huomattavasti sen yhteensopivuusluettelo ei tarjoa yleistä fs-korvaajaa, joka vastaisi Node-tiedostojärjestelmää.

Tuo ero on tärkeä. JavaScript-työkalut voidaan usein toistaa selaimessa. Mielivaltainen pääsy isäntä-/palvelintiedostojärjestelmään on suorituskyky, ei vain puuttuva apufunktio.

Jos todella tarvitset selaintyönkulun, valitse selainnatiivi suunnittelu tarkkaan tehtävään – esimerkiksi hae resurssi URL-osoitteesta, anna käyttäjän valita tiedosto tai tallenna sovellusdata käyttämällä sopivaa selain-tallennusmekanismia. Älä arvioi menestystä vain sen perusteella, lakkaako Webpack näyttämästä virhettä.

Vaihtoehto 4: Suosi selainyhteensopivaa riippuvuutta tai paketin exporttia

Jos virhe tulee kolmannen osapuolen paketista, tutki, tukeeko paketti selaimia virallisesti. Webpackin nykyinen paketin exports-opas selittää, että paketit voivat tarjota ehdollisia exportteja ympäristöille, kuten browser ja node. Webpackin julkaisuohjeet suosittelevat myös, että paketin tekijät tarjoavat frontend-yhteensopivia vaihtoehtoja, kun Node-kohtaiset toteutukset eivät sovellu selaimille.

Esimerkiksi paketti voi käsitteellisesti paljastaa:

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

Jos päivitetty paketiversio tarjoaa oikean selainentry-pisteen, kun taas vanhempi versiosi ei tee sitä, päivitys voi olla turvallisempi kuin fs: false -konfigurointi. Samoin Node-kohtaisen paketin korvaaminen selaimelle nimenomaisesti suunnitellulla paketilla voi vähentää yhteensopivuushakkerointia ja paketin monimutkaisuutta.

Valitse tämä reitti, kun: riippuvuuden on tarkoitus toimia selaimissa, mutta asennettu versio valitsee tai paljastaa Node-kohtaisen toteutuksen.

Kompromissi: paketin päivitys tai korvaaminen voi tuoda API-muutoksia, joten aja normaaleja sovellustestejäsi äläkä pidä onnistunutta käännöstä riittävänä.

Vaihtoehto 5: Jos tulos on Node-paketti, aseta kohde Nodeksi

Joissakin tapauksissa Webpack ei tuota lainkaan selainkoodia. Saatatat kääntää CLI-työkalua, taustatyöläistä, käännöstyökalua, SSR-palvelinta tai Node-palvelua. Tällöin fs:n vaimentaminen yrittäminen on taaksepäin: suoritusympäristö tarjoaa sen todellisuudessa.

Webpackin virallinen Targets-dokumentaatio sanoo, että:

module.exports = {
  target: 'node'
}

kääntää Node.js:n kaltaiselle ympäristölle ja jättää natiivit moduulit, kuten fs ja path, Noden tarjottaviksi suoritusajassa.

Webpackin yksityiskohtaisempi target-konfiguraatioviite erottaa myös web, node, Electron-kohderyhmät, web-työläiset ja muut ympäristöt.

Käytä target: 'node' -asetusta, kun: tuloksena oleva JavaScript suoritetaan Noden alla.

Älä käytä sitä “korjaamaan” normaalia selain-SPA:ta: kohteen muuttaminen ei saa selainta yhtäkkiä tarjoamaan Noden tiedostojärjestelmärajapintoja. Se muuttaa ympäristöä, jonka Webpack oletaa suorittavan paketin.

Edistyneet Node-käännökset: externals voi pitää natiivit suoritusajassa

Palvelinpaketeille Webpack tarjoaa myös Node-kohtaisen externals-käyttäytymisen. Sen virallinen Externals-dokumentaatio toteaa, että externalsPresets.node voi käsitellä Node:n natiiveja moduuleja, kuten fs, path ja vm, ulkoisina ja ladata ne Noden suoritusajan require():lla.

Tyypillinen Node-kohtainen konfiguraatio voisi siis näyttää tältä:

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

Tämä on edistynyt palvelinpaketin huolenaihe, ei selainkiertotie.

Vaihe 4: Käännä uudelleen, testaa sitten ominaisuus, joka aiheutti tuonnin

Tehdessäsi arkkitehtonisen tai konfiguraatiomuutoksen, käännä uudelleen:

npm run build

• Jos siirsit tiedostopääsyn palvelimelle, kutsu selainominaisuutta ja varmista, että palvelinpää palauttaa odotetun datan.
• Jos asetit fs: false, käytä riippuvuutta selaimessa ja vahvista, ettei se koskaan mene tiedostojärjestelmästä riippuvaiseen haaraan.
• Jos vaihdoit paketin selainkäännökseen, aja paketin todellinen käyttäjäkohtainen työnkulku.
• Jos muutit kohteen Nodeksi, suorita käännetty tulos tukemallasi Node-versiolla.

Yleiset korjaukset verrattuna

Erityistapaus: jaettu koodi, jonka tuovat sekä selain- että palvelinpaketit

Tämän virheen yleinen lähde on apumoduuli, joka sisältää sekä puhtaita funktioita että Node-kohtaisia apufunktioita:

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

Even if your browser imports only formatDate, the top-level fs import can force Webpack to resolve fs. A cleaner design is to split the modules:

Jos selaimesi tuo vain formatDate:n, ylimmän tason fs-tuonti voi pakottaa Webpackin ratkaisemaan fs:n. Puhtaampi suunnittelu on jakaa moduulit:

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

Tämä tekee suoritusympäristön rajasta näkyvän moduuligraafissa sen sijaan, että luotettaisiin tree-shakingiin tai fallbackiin yhteensopimattoman tuonnin poistamiseksi.

Erityistapaus: virhe ilmestyi päivityksen jälkeen Webpack 4:stä

Tämä on yksi klassisista Webpack 5 -migraatio-oireista. Webpack 4 toimitti automaattisesti yhteensopivuusshimejä monille Node:n ydinmoduuleille. Webpack 5 lopetti sen tarkoituksellisesti. Jos koodisi “toimi ennen päivitystä”, kysy, tarvitsiko se todella Node-ominaisuutta selaimessa vai injektiko vanha bundler hiljaa yhteensopivuuskoodia.

Virallinen Webpack-migraatioopas suosittelee lukemaan käännösvirheen breaking-change-ohjeet ja korvaamaan vanhat node.*-yhteensopivuuskonfiguraatiot uudemmalla resolver-lähestymistavalla, kun se on aiheellista.

Älä oleta, että kaikkien Webpack 4 -polyfillien luominen uudelleen on paras migraatio. Webpackin omat julkaisumuistiinpanot suosittelevat frontend-yhteensopivia moduuleja, kun mahdollista.

Lopullinen itsetarkistus

Ennen asian sulkemista, varmista nämä kohdat:

1. Etsi tarkka lähdetiedosto tai riippuvuus, joka tuo fs:n.
2. Vahvista, toimiiko kärsinyt paketti selaimessa vai Nodessa.
3. Jos se on selainpaketti, varmista, tarvitseeko ominaisuus todella tiedostojärjestelmäkäyttäytymistä.
4. Jos tarvitsee, siirrä tiedostojärjestelmäoperaatio palvelinrajan taakse.
5. Jos riippuvuuden fs-käyttö on valinnaista eikä sitä koskaan suoriteta selaimessa, harkitse resolve.fallback: { fs: false }.
6. Jos paketti virallisesti tarjoaa selainexportin, suosi sitä pakotetun käyttäytymisen vaimentamisen sijaan.
7. Jos paketti suoritetaan Nodessa, käytä Node-kohderyhmää web-kohderyhmän sijaan.
8. Käännä uudelleen ja varmista, että moduuliresoluutiovirhe on poissa.
9. Suorita todellinen ominaisuus, joka aiemmin toi fs:n; älä lopeta “käännös onnistui” -tilaan.

Kestävä korjaus on koodin linjaaminen sen suoritusympäristön kanssa. fs kuuluu Noden tiedostojärjestelmäympäristöön. Webpack 5 tekee tuon rajan näkyvämmäksi olemalla enää injektioimatta Node:n ydinpolyfillejä automaattisesti. Kun olet päättänyt, kuuluuko tiedostojärjestelmätyö palvelimelle, onko se valinnaista selaimessa vai osa Node-kohdennettua pakettia, oikean konfiguraation valitseminen on paljon helpompaa.