Kā novērst kļūdu “Module Not Found: Can’t Resolve fs” programmā Webpack

Pēdējoreiz pārbaudīts: 2026. gada 11. septembrī. Kļūda “Module not found: Error: Can’t resolve 'fs'” parasti nozīmē, ka Webpack veido kodu pārlūkam, taču jūsu avota kods vai viena no tā atkarībām importē Node.js failu sistēmas moduli. Node dokumentācija apraksta node:fs kā API mijiedarbībai ar failu sistēmu, savukārt Webpack pašreizējā dokumentācija norāda, ka Webpack 5 vairs automātiski nepievieno Node.js kodola moduļu polifillus pārlūka būvēšanai.

Svarīgākā daļa ir izvēlēties risinājumu, kas atbilst tam, ko kods patiesībā mēģina izdarīt. Nav viena iestatījuma, kas būtu pareizs katram projektam. Ja jūsu lietojumprogrammai tiešām ir nepieciešams lasīt failus no servera diska, pārvietojiet šo darbību uz Node/servera kodu. Ja atkarība importē fs tikai neobligātai tikai Node paredzētai funkcijai, ko jūsu pārlūka pakotne nekad neizmanto, var būt piemērots resolve.fallback: { fs: false }. Ja pakotnei ir pārlūkā saderīga būve, izmantojiet to. Un, ja pakotne ir paredzēta darbībai Node vidē, norādiet Node mērķi, nevis mēģiniet to uzskatīt par tīmekļa pakotni.

Ātra lēmumu tabula

Webpack oficiālā resolve.fallback dokumentācija norāda, ka Webpack 5 vairs automātiski nepievieno Node kodola moduļu polifillus. Tās Webpack 5 izlaišanas piezīmes izskaidro iemeslu: automātiskie polifilli varēja pievienot lielu, nevajadzīgu saderības kodu frontend pakotnēm, tāpēc Webpack nodeva atbildību lietotnes vai pakotnes autoram.

1. solis: Noskaidrojiet, kas importē fs

Sāciet ar pirmo noderīgo rindu Webpack kļūdas izvades. Parasti tā norāda uz failu, kurā atrisināšana neizdevās, piemēram:

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

Ja kļūdainais fails ir jūsu, meklējiet tajā vienu no šīm formām:

const fs = require('fs')

// vai
import fs from 'node:fs'

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

Node oficiālā failu sistēmas dokumentācija apstiprina, ka node:fs un node:fs/promises ir Node API failu sistēmas darbībām. Parasta pārlūka pakotne neiegūst piekļuvi servera diskam tikai tāpēc, ka Webpack var parsēt importu.

Ja kļūdainais fails atrodas node_modules, nekavējoties needitējiet šo pakotni uz vietas. Vispirms identificējiet, kura augstākā līmeņa atkarība to ienesa jūsu pārlūka pakotnē. Noderīgais jautājums nav tikai “Kura pakotne importē fs?” bet gan “Kāpēc šis Node orientētais koda ceļš ir sasniedzams no mana klienta ieejas punkta?”

Izmantojiet šo diagnostiku, kad: kļūda parādās pēc Webpack atjaunināšanas, pievienojot atkarību, importējot iepriekš tikai serverim paredzētu utilītu frontend kodā vai pārvietojot kopīgu kodu uz klienta pakotni.

Praktiska pārbaude: pagaidām noņemiet importu, kas noved pie kļūdainā moduļa, un pārbūvējiet. Ja fs kļūda pazūd, esat apstiprinājis atkarību ceļu, pirms maināt Webpack konfigurāciju.

2. solis: Ja kodam tiešām ir nepieciešama piekļuve failu sistēmai, pārvietojiet to uz Node/servera kodu

Tas ir labākais risinājums, kad kodam ir jālasa konfigurācijas faili, veidnes, lokāli dokumenti, privātās atslēgas, ģenerētie resursi, servera žurnāli vai jebkas cits no mašīnas failu sistēmas.

Piemēram, tas ir piemēroti Node vidē:

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

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

Bet to nevajadzētu ievilkt pārlūka ieejas punktā. Tā vietā atklājiet rezultātu caur jūsu lietojumprogrammas servera slāni. Vienkāršota sadalīšana varētu būt:

// servera puses kods
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)
})

// pārlūka puses kods
export async function loadTemplate() {
  const response = await fetch('/api/template')
  if (!response.ok) throw new Error('Failed to load template')
  return response.text()
}

Kompromiss ir arhitektūras: jūs pievienojat servera galapunktu vai citu servera puses robežu, bet saglabājat fs semantiku. Pārlūks pieprasa datus; serveris lasa failu sistēmu.

Šis risinājums ir piemērots, kad: failu sistēmas darbība ir reāla un nepieciešama.

Šis risinājums nav nepieciešams, kad: imports eksistē tikai neobligātā Node koda ceļā, ko pārlūks nekad neizpilda. Šajā gadījumā pārlūkam specifisks pakotnes ieejas punkts vai ignorēts fallback var būt tīrāks.

3. solis: Izmantojiet resolve.fallback: { fs: false } tikai tad, ja failu sistēmas uzvedība ir neobligāta

Webpack oficiālā Webpack 4 uz 5 migrācijas rokasgrāmata īpaši norāda, ka konfigurācijas, kas izmantoja veco modeli node.fs: 'empty', jāpārvieto uz:

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

Skatiet oficiālo Webpack 5 migrācijas rokasgrāmatu.

Fallback iestatīšana uz false norāda Webpack neiekļaut implementāciju šim neatrisinātajam modulim. Tas var būt tieši pareizi pakotnei, kas satur aizsargātu tikai Node zaru, piemēram, kodu, kas izmanto fs tikai servera renderēšanas vai CLI izpildes laikā.

Tas var arī slēpt būves kļūdu, atstājot jūs ar izpildes laika dizaina kļūdu. Apsveriet šo atkarību:

const fs = require('fs')

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

Ja jūsu pārlūks patiešām izsauc loadUserConfig(), fs aizstāšana ar “nekā” neizveido funkcionējošu pārlūka failu sistēmu. Būve var turpināties, bet funkcija joprojām nevar veikt paredzēto Node darbību.

Izmantojiet fs: false, kad: esat pārbaudījis, ka failu sistēmai specifiskais zars netiek izmantots tīmekļa mērķī.

Neizmantojiet to, kad: jūsu pārlūka funkcija ir atkarīga no readFileSync, direktoriju pārlūkošanas, servera ceļiem vai citas reālas Node failu sistēmas uzvedības.

Kāpēc “vienkārši instalējiet fs polifillu” parasti ir nepareiza pirmā atbilde

Webpack pašreizējā resolve.fallback dokumentācija sniedz piemērus manuāliem polifilliem vairākiem Node kodola moduļiem, piemēram, path, buffer, stream un crypto. Īpaši jāatzīmē, ka tās saderības sarakstā nav vispārīga fs aizstājēja, kas būtu ekvivalents Node failu sistēmai.

Šī atšķirība ir svarīga. JavaScript utilītus bieži var reproducēt pārlūkā. Patvaļīga piekļuve saimniekservera failu sistēmai ir izpildes vides iespēja, nevis tikai trūkstoša palīgfunkcija.

Ja jums patiešām ir nepieciešama pārlūka darba plūsma, izvēlieties pārlūkam raksturīgu dizainu konkrētajam uzdevumam — piemēram, ielādējiet resursu no URL, ļaujiet lietotājam izvēlēties failu vai glabājiet lietojumprogrammas datus, izmantojot atbilstošu pārlūka glabāšanas mehānismu. Nevērtējiet panākumus tikai pēc tā, vai Webpack pārstāj rādīt kļūdu.

4. opcija: Dodiet priekšroku pārlūkā saderīgai atkarībai vai pakotnes eksportam

Ja kļūda nāk no trešās puses pakotnes, pārbaudiet, vai šī pakotne oficiāli atbalsta pārlūkus. Webpack pašreizējā pakotnes exports rokasgrāmata izskaidro, ka pakotnes var nodrošināt nosacītus eksportus vidēm, piemēram, browser un node. Webpack izlaišanas norādījumi arī iesaka pakotņu autoru nodrošināt frontend saderīgas alternatīvas, kad tikai Node implementācijas nav piemērotas pārlūkiem.

Piemēram, pakotne var konceptuāli eksponēt:

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

Ja atjaunināta pakotnes versija nodrošina pareizu pārlūka ieejas punktu, bet jūsu vecākā versija to nedara, atjaunināšana var būt drošāka nekā konfigurēt fs: false. Tāpat Node orientētas pakotnes aizstāšana ar tādu, kas ir īpaši paredzēta lietošanai pārlūkā, var samazināt saderības trikus un pakotnes sarežģītību.

Izvēlieties šo ceļu, kad: atkarībai ir jādarbojas pārlūkos, bet instalētā versija atlasa vai eksponē tikai Node implementāciju.

Kompromiss: pakotnes atjaunināšana vai aizstāšana var ieviest API izmaiņas, tāpēc palaidiet parastos lietojumprogrammas testus, nevis uzskatiet veiksmīgu kompilāciju par pietiekamu.

5. opcija: Ja izvade ir Node pakotne, iestatiet mērķi uz Node

Dažreiz Webpack vispār nerada pārlūka kodu. Jūs varat būvēt CLI, fona darbinieku, būvēšanas rīku, SSR serveri vai Node servisu. Šajā gadījumā mēģinājums apspiest fs ir pretējs: izpildes vide to faktiski nodrošina.

Webpack oficiālā Mērķu dokumentācija norāda, ka:

module.exports = {
  target: 'node'
}

tulko Node.js līdzīgai videi un atstāj iebūvētos moduļus, piemēram, fs un path, lai Node nodrošinātu tos izpildes laikā.

Webpack detalizētā mērķa konfigurācijas atsauce arī atšķir web, node, Electron mērķus, tīmekļa darbiniekus un citas vides.

Izmantojiet target: 'node', kad: iegūtais JavaScript izpildīsies zem Node.

Neizmantojiet to, lai “labotu” parasto pārlūka SPA: mērķa maiņa nepārvērš pārlūku tā, lai tas pēkšņi nodrošinātu Node failu sistēmas API. Tas maina to, kādu vidi Webpack pieņem, ka izpildīs pakotni.

Uzlabotas Node būves: externals var saglabāt iebūvētos moduļus izpildes laikā

Servera pakotnēm Webpack arī nodrošina Node orientētu externals uzvedību. Tās oficiālā Externals dokumentācija norāda, ka externalsPresets.node var uzskatīt Node iebūvētos moduļus, piemēram, fs, path un vm, par ārējiem un ielādēt tos ar Node izpildes require().

Tāpēc tipiska Node orientēta konfigurācija varētu izskatīties šādi:

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

Tas ir uzlabots servera pakotnes jautājums, nevis pārlūka apvedceļš.

4. solis: Pārbūvējiet, pēc tam pārbaudiet funkciju, kas izraisīja importu

Pēc arhitektūras vai konfigurācijas izmaiņu veikšanas pārbūvējiet:

npm run build

Tīra kompilācija pierāda tikai to, ka moduļa atrisināšana bija veiksmīga. Tā nepierāda, ka ietekmētā funkcija uzvedas pareizi. Testējiet atbilstoši izvēlētajam risinājumam:

• Ja pārvietojāt failu piekļuvi uz serveri, izsauciet pārlūka funkciju un pārbaudiet, vai servera galapunkts atgriež paredzētos datus.
• Ja iestatījāt fs: false, izpildiet atkarību pārlūkā un pārliecinieties, ka tā nekad neieiet failu sistēmai atkarīgajā zarā.
• Ja pārslēdzāties uz pakotnes pārlūka būvi, palaidiet pakotnes reālo lietotājam paredzēto darba plūsmu.
• Ja mainījāt mērķi uz Node, izpildiet būvēto izvadi zem atbalstītās Node versijas.

Bieži sastopamo risinājumu salīdzinājums

Īpašs gadījums: kopīgs kods, ko importē gan pārlūka, gan servera pakotnes

Biežs šīs kļūdas avots ir utilītu modulis, kas satur gan tīras funkcijas, gan tikai Node palīgfunkcijas:

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

Pat ja jūsu pārlūks importē tikai formatDate, augstākā līmeņa fs imports var piespiest Webpack atrisināt fs. Tīrāks dizains ir sadalīt modulius:

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

Tas padara izpildes robežu redzamu moduļu grafā, nevis paļaujas uz tree-shaking vai fallback, lai noņemtu nesaderīgu importu.

Īpašs gadījums: kļūda parādījās pēc atjaunināšanas no Webpack 4

Tas ir viens no klasiskajiem Webpack 5 migrācijas simptomiem. Webpack 4 automātiski piegādāja saderības shims daudziem Node kodola moduļiem. Webpack 5 apzināti pārtrauca to darīt. Ja jūsu kods “strādāja pirms atjaunināšanas”, jautājiet, vai tam tiešām bija nepieciešama Node funkcija pārlūkā, vai vecais bundleris klusi injicēja saderības kodu.

Oficiālā Webpack migrācijas rokasgrāmata iesaka izlasīt būves kļūdas norādījumus par mainītām saderības īpašībām un, kur piemērots, aizstāt veco node.* saderības konfigurāciju ar jaunāko risinātāja pieeju.

Neuzskatiet, ka visu Webpack 4 polifillu atjaunošana ir labākā migrācija. Webpack paša izlaišanas piezīmes iesaka frontend saderīgus moduļus, kur vien iespējams.

Galīgā pašpārbaude

Pirms slēgt problēmu, pārbaudiet šos punktus:

1. Atrodiet precīzo avota failu vai atkarību, kas importē fs.
2. Apstipriniet, vai ietekmētā pakotne darbojas pārlūkā vai Node vidē.
3. Ja tā ir pārlūka pakotne, pārbaudiet, vai funkcijai tiešām ir nepieciešama failu sistēmas uzvedība.
4. Ja ir, pārvietojiet failu sistēmas darbību aiz servera robežas.
5. Ja atkarības fs lietojums ir neobligāts un nekad netiek izpildīts pārlūkā, apsveriet resolve.fallback: { fs: false }.
6. Ja pakotne oficiāli nodrošina pārlūka eksportu, dodiet priekšroku tam, nevis nepieciešamās uzvedības apspiešanai.
7. Ja pakotne izpildās Node vidē, izmantojiet Node mērķi, nevis tīmekļa mērķi.
8. Pārbūvējiet un pārliecinieties, ka moduļa atrisināšanas kļūda ir pazudusi.
9. Palaidiet faktisko funkciju, kas iepriekš ievilka fs; neapstājieties pie “kompilēts veiksmīgi”.

Ilgstošais risinājums ir saskaņot kodu ar tā izpildes vidi. fs pieder Node failu sistēmas videi. Webpack 5 padara šo robežu redzamāku, vairs neinjicējot Node kodola polifillus automātiski. Kad esat nolēmis, vai failu sistēmas darbs pieder serverim, ir neobligāts pārlūkā vai ir daļa no Node mērķa pakotnes, pareizo konfigurāciju kļūst daudz vieglāk izvēlēties.