Kaip išspręsti klaidą „Module Not Found: Can’t Resolve fs“ Webpack

Paskutinį kartą patikrinta: 2026 m. rugsėjo 11 d. Klaida „Module not found: Error: Can’t resolve 'fs'“ paprastai reiškia, kad Webpack kuria kodą naršyklei, tačiau jūsų šaltinio kodas arba viena iš jo priklausomybių importuoja Node.js failų sistemos modulį. Node dokumentuose node:fs apibūdinamas kaip API sąveikai su failų sistema, o dabartinė Webpack dokumentacija nurodo, kad Webpack 5 nebeprofiliuoja Node.js pagrindinių modulių naršyklės kompiliacijoms automatiškai.

Svarbiausia yra pasirinkti sprendimą, atitinkantį tai, ką kodas iš tikrųjų bando padaryti. Nėra vieno nustatymo, kuris būtų teisingas kiekvienam projektui. Jei jūsų programai iš tikrųjų reikia skaityti failus iš serverio disko, perkelti šį darbą į Node/serverio kodą. Jei priklausomybė importuoja fs tik pasirinktinai Node funkcijai, kurios jūsų naršyklės paketas niekada nenaudoja, gali būti tinkamas resolve.fallback: { fs: false }. Jei paketas turi naršyklėje suderinamą kompiliaciją, naudokite ją. O jei paketas skirtas veikti Node aplinkoje, nukreipkite į Node, o ne apsimetinėkite, kad tai yra žiniatinklio paketas.

Greito sprendimo lentelė

Webpack oficiali resolve.fallback dokumentacija teigia, kad Webpack 5 nebeprofiliuoja Node pagrindinių modulių automatiškai. Jos Webpack 5 leidimo pastabos paaiškina priežastį: automatiniai profiliai galėjo pridėti didelį, nereikalingą suderinamumo kodą į frontend paketus, todėl Webpack perkėlė atsakomybę į programą arba paketo autorių.

1 žingsnis: Sužinokite, kas importuoja fs

Pradėkite nuo pirmosios naudingos eilutės Webpack klaidos išvestyje. Ji paprastai nurodo failą, kuriame nepavyko išspręsti modulio, pvz.:

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

Jei nepavykęs failas yra jūsų, ieškokite jame vienos iš šių formų:

const fs = require('fs')

// arba
import fs from 'node:fs'

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

Node oficiali failų sistemos dokumentacija patvirtina, kad node:fs ir node:fs/promises yra Node API failų sistemos operacijoms. Įprastas naršyklės paketas negauna prieigos prie serverio disko vien todėl, kad Webpack gali išanalizuoti importą.

Jei nepavykęs failas yra node_modules kataloge, nedelsiant redaguokite tą paketą vietoje. Pirmiausia nustatykite, kuri aukščiausio lygio priklausomybė atvedė ją į jūsų naršyklės paketą. Naudingas klausimas yra ne tik „Kuris paketas importuoja fs?“, bet ir „Kodėl tas Node orientuotas kodo kelias yra pasiekiamas iš mano kliento įėjimo?“

Naudokite šią diagnostiką, kai: klaida atsiranda po Webpack atnaujinimo, pridedant priklausomybę, importuojant anksčiau tik serveriui skirtą įrankį į frontend kodą arba perkelti bendrą kodą į kliento paketą.

Praktinis patikrinimas: laikinai pašalinkite importą, kuris veda į nepavykusį modulį, ir persikompiliuokite. Jei fs klaida dingsta, esate patvirtinę priklausomybės kelią prieš keisdami Webpack konfigūraciją.

2 žingsnis: Jei kodui iš tikrųjų reikia prieigos prie failų sistemos, perkelti jį į Node/serverio kodą

Tai yra geriausias sprendimas, kai kodui reikia skaityti konfigūracijos failus, šablonus, vietinius dokumentus, privačius raktus, sugeneruotus turtus, serverio žurnalus ar bet ką kita iš mašinos failų sistemos.

Pavyzdžiui, tai yra tinkama Node aplinkoje:

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

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

Tačiau tai neturėtų būti įtraukta į naršyklės įėjimą. Vietoj to, atskleiskite rezultatą per jūsų programos serverio sluoksnį. Supaprastintas padalijimas galėtų būti:

// serverio pusės kodas
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)
})

// naršyklės pusės kodas
export async function loadTemplate() {
  const response = await fetch('/api/template')
  if (!response.ok) throw new Error('Failed to load template')
  return response.text()
}

Kompromisas yra architektūrinis: pridedate serverio galinį tašką arba kitą serverio pusės ribą, tačiau išlaikote fs semantiką. Naršyklė užklauso duomenų; serveris skaito failų sistemą.

Šis sprendimas yra tinkamas, kai: failų sistemos operacija yra reali ir būtina.

Šis sprendimas nėra būtinas, kai: importas egzistuoja tik pasirinktiniame Node kodo kelyje, kurio naršyklė niekada nevykdo. Tokiu atveju naršyklei specifinis paketo įėjimas arba ignoruojamas atsarginis variantas gali būti švaresnis.

3 žingsnis: Naudokite resolve.fallback: { fs: false } tik tada, kai failų sistemos elgsena yra pasirinktinė

Oficiali Webpack 4-to-5 migracijos vadovas konkrečiai teigia, kad konfigūracijos, naudojantys senąjį šabloną node.fs: 'empty', turėtų pereiti prie:

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

Žiūrėkite oficialų Webpack 5 migracijos vadovą.

Atsarginio varianto nustatymas į false nurodo Webpack neįtraukti to neišspręsto modulio implementacijos. Tai gali būti visiškai teisinga paketui, kuriame yra saugomas Node tik šakos kodas, pvz., kodas, kuris naudoja fs tik serverio atvaizdavimo ar CLI vykdymo metu.

Tai taip pat gali paslėpti kompiliavimo klaidą, paliekant jus su vykdymo metu dizaino klaida. Apsvarstykite šią priklausomybę:

const fs = require('fs')

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

Jei jūsų naršyklė iš tikrųjų kviečia loadUserConfig(), pakeitus fs į „nieką“, nesukuria veikiančios naršyklės failų sistemos. Kompiliacija gali tęstis, tačiau funkcija vis tiek negali atlikti numatytos Node operacijos.

Naudokite fs: false, kai: esate patikrinę, kad failų sistemai specifinė šaka nėra naudojama žiniatinklio tikslui.

Nenaudokite jo, kai: jūsų naršyklės funkcija priklauso nuo readFileSync, katalogų perėjimo, serverio kelių ar kitos realios Node failų sistemos elgsenos.

Kodėl „tiesiog įdiekite fs profilį“ paprastai yra neteisingas pirmasis atsakymas

Dabartinė Webpack resolve.fallback dokumentacija pateikia rankinių profilių pavyzdžių keliems Node pagrindiniams moduliams, tokiems kaip path, buffer, stream ir crypto. Svarbu, kad jos suderinamumo sąraše nėra bendro fs pakaitalo, ekvivalentiško Node failų sistemai.

Tas skirtumas yra svarbus. JavaScript įrankius dažnai galima atkartoti naršyklėje. Savavališka prieiga prie pagrindinio/serverio failų sistemos yra vykdymo galimybė, o ne tik trūkstama pagalbinė funkcija.

Jei iš tikrųjų jums reikia naršyklės darbo eigos, pasirinkite naršyklei natyvų dizainą konkrečiai užduočiai – pvz., gauti turtą iš URL, leisti vartotojui pasirinkti failą arba saugoti programos duomenis naudojant tinkamą naršyklės saugyklos mechanizmą. Nevertinkite sėkmės tik pagal tai, ar Webpack nustoja rodyti klaidą.

4 variantas: Pirmenybė teikiama naršyklėje suderinamai priklausomybei arba paketo eksportui

Jei klaida kyla iš trečiosios šalies paketo, patikrinkite, ar tas paketas oficialiai palaiko naršykles. Dabartinis Webpack paketo exports vadovas paaiškina, kad paketai gali teikti sąlyginius eksportus aplinkoms, tokioms kaip browser ir node. Webpack leidimo gairės taip pat rekomenduoja paketo autoriams teikti frontend suderinamas alternatyvas, kai Node tik implementacijos netinka naršyklėms.

Pavyzdžiui, paketas konceptualiai gali atskleisti:

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

Jei atnaujinta paketo versija teikia tinkamą naršyklės įėjimą, o jūsų senesnė versija – ne, atnaujinimas gali būti saugesnis nei fs: false konfigūravimas. Taip pat pakeitus Node orientuotą paketą į tokį, kuris yra aiškiai sukurtas naršyklei, galima sumažinti suderinamumo triukus ir paketo sudėtingumą.

Pasirinkite šį kelią, kai: priklausomybė turėtų veikti naršyklėse, tačiau įdiegta versija pasirenka arba atskleidžia Node tik implementaciją.

Kompromisas: paketo atnaujinimas arba pakeitimas gali įvesti API pakeitimų, todėl vykdykite įprastus programos testus, o ne laikykite sėkmingą kompiliavimą pakankamu.

5 variantas: Jei išvestis yra Node paketas, nustatykite tikslą į Node

Kartais Webpack visai nekompiliuoja naršyklės kodo. Galite kompiliuoti CLI, fono darbuotoją, kompiliavimo įrankį, SSR serverį arba Node paslaugą. Tokiu atveju bandymas slopinti fs yra atvirkštinis: vykdymo aplinka jį iš tikrųjų teikia.

Webpack oficiali Targets dokumentacija teigia, kad:

module.exports = {
  target: 'node'
}

kompiliuoja aplinkai, panašiai į Node.js, ir palieka integruotus modulius, tokius kaip fs ir path, kad Node juos pateiktų vykdymo metu.

Išsamesnė Webpack target konfigūracijos nuoroda taip pat skiria web, node, Electron tikslus, žiniatinklio darbuotojus ir kitas aplinkas.

Naudokite target: 'node', kai: gautas JavaScript bus vykdomas Node aplinkoje.

Nenaudokite jo „ištaisyti“ įprastą naršyklės SPA: tikslo keitimas nepavirs naršyklės staiga teikiančios Node failų sistemos API. Tai pakeičia aplinką, kurią Webpack daro prielaidą, kad vykdys paketą.

Išplėstinės Node kompiliacijos: externals gali palikti integruotus modulius vykdymo metu

Serverio paketams Webpack taip pat teikia Node orientuotą externals elgseną. Jo oficiali Externals dokumentacija teigia, kad externalsPresets.node gali laikyti Node integruotus modulius, tokius kaip fs, path ir vm, išoriniais ir įkelti juos su Node vykdymo require().

Tipinė Node orientuota konfigūracija todėl galėtų atrodyti taip:

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

Tai yra išplėstinis serverio paketo klausimas, o ne naršyklės apėjimas.

4 žingsnis: Persikompiliuokite, tada išbandykite funkciją, kuri sukėlė importą

Po architektūrinio arba konfigūracinio pakeitimo, persikompiliuokite:

npm run build

Švari kompiliacija įrodo tik tai, kad modulių sprendimas pavyko. Tai neįrodo, kad paveikta funkcija veikia teisingai. Testuokite pagal pasirinktą sprendimą:

• Jei perkėlėte failų prieigą į serverį, iškvieskite naršyklės funkciją ir patikrinkite, ar serverio galinis taškas grąžina tikėtus duomenis.
• Jei nustatėte fs: false, išbandykite priklausomybę naršyklėje ir patvirtinkite, kad ji niekada nepatenka į failų sistemai priklausomą šaką.
• Jei perėjote prie paketo naršyklės kompiliacijos, vykdykite tikrą paketo vartotojui skirtą darbo eigą.
• Jei pakeitėte tikslą į Node, vykdykite sukurtą išvestį palaikomoje Node versijoje.

Paprastų sprendimų palyginimas

Specialus atvejis: bendras kodas, kurį importuoja tiek naršyklės, tiek serverio paketai

Dažnas šios klaidos šaltinis yra įrankių modulis, kuriame yra tiek grynos funkcijos, tiek Node tik pagalbinės priemonės:

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

Net jei jūsų naršyklė importuoja tik formatDate, aukščiausio lygio fs importas gali priversti Webpack išspręsti fs. Švaresnis dizainas yra padalinti 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')
}

Tai padaro vykdymo ribą matomą modulio grafike, o ne pasikliauja tree-shaking arba atsarginiu variantu, kad būtų pašalintas nesuderinamas importas.

Specialus atvejis: klaida atsirado po atnaujinimo iš Webpack 4

Tai yra vienas iš klasikinių Webpack 5 migracijos simptomų. Webpack 4 automatiškai teikė suderinamumo shim daugeliui Node pagrindinių modulių. Webpack 5 sąmoningai nustoto tai daryti. Jei jūsų kodas „veikė prieš atnaujinimą“, paklauskite, ar jis iš tikrųjų reikalavo Node funkcijos naršyklėje, ar senasis kompiliatorius tyliai įterpė suderinamumo kodą.

Oficialus Webpack migracijos vadovas rekomenduoja skaityti kompiliavimo klaidos nurodymus dėl lūžančių pakeitimų ir pakeisti seną node.* suderinamumo konfigūraciją naujesniu resolverio požiūriu, kai tinkama.

Nedarykite prielaidos, kad kiekvieno Webpack 4 profilio atkūrimas yra geriausia migracija. Webpack pačio leidimo pastabos rekomenduoja frontend suderinamus modulius, kai įmanoma.

Galutinis savikontrolės sąrašas

Prieš uždarydami problemą, patikrinkite šiuos punktus:

1. Raskite tikslų šaltinio failą arba priklausomybę, kuri importuoja fs.
2. Patvirtinkite, ar paveiktas paketas veikia naršyklėje, ar Node aplinkoje.
3. Jei tai naršyklės paketas, patikrinkite, ar funkcija iš tikrųjų reikalauja failų sistemos elgsenos.
4. Jei taip, perkelti failų sistemos operaciją už serverio ribos.
5. Jei priklausomybės fs naudojimas yra pasirinktinis ir niekada nevykdomas naršyklėje, svarstykite resolve.fallback: { fs: false }.
6. Jei paketas oficialiai teikia naršyklės eksportą, pirmenybę teikite tam, o ne būtinos elgsenos slopinimui.
7. Jei paketas vykdomas Node aplinkoje, naudokite Node tikslą, o ne žiniatinklio tikslą.
8. Persikompiliuokite ir patvirtinkite, kad modulių sprendimo klaida dingo.
9. Vykdykite faktinę funkciją, kuri anksčiau įtraukė fs; nesustokite ties „sėkmingai sukompiliuota“.

Patvarus sprendimas yra suderinti kodą su jo vykdymo aplinka. fs priklauso Node failų sistemos aplinkai. Webpack 5 padaro tą ribą matomesnę nebeprofiliuodamas Node pagrindinių modulių automatiškai. Kai nuspręsite, ar failų sistemos darbas priklauso serveriui, yra pasirinktinis naršyklėje, ar yra dalis Node orientuoto paketo, teisingą konfigūraciją pasirinkti tampa daug lengviau.