nod.JS V15. 8. 0 documentație

în nod.sistemul modulului js, fiecare fișier este tratat ca un modul separat. De exemplu, ia în considerare un fișier numit foo.js:

const circle = require('./circle.js');console.log(`The area of a circle of radius 4 is ${circle.area(4)}`);

Pe prima linie, foo.js încarcă modulul circle.js care este în samedirectory ca foo.js.,

Iată conținutul circle.js:

const { PI } = Math;exports.area = (r) => PI * r ** 2;exports.circumference = (r) => 2 * PI * r;

modulul circle.js a exportat funcțiile area() șicircumference(). Funcțiile și obiectele sunt adăugate la rădăcina unui modulprin specificarea proprietăților suplimentare pe obiectul special exports.variabilele locale ale modulului vor fi private, deoarece modulul este înfășuratîn funcție de nod.în acest exemplu, variabila PIeste privată la circle.js.,

module.exports proprietate poate fi atribuită o nouă valoare (cum ar fi un functionor obiect).

mai Jos, bar.js face uz de square module, care exportă un Pătrat clasa:

const Square = require('./square.js');const mySquare = new Square(2);console.log(`The area of mySquare is ${mySquare.area()}`);

square modulul este definit în square.js:

modulul sistem este implementat în require('module') module.

accesarea modulului principal#

când un fișier este rulat direct de la nod.js, require.main este setat lamodule., Aceasta înseamnă că este posibil să se determine dacă un fișier a fostrulați direct prin testarea require.main === module.

Pentru un fișier foo.js, acest lucru va fi true dacă a rula prin intermediul node foo.js, darfalse dacă condusă de require('./foo').

module oferă un filename proprietate (în mod normal, echivalent cu__filename), punctul de intrare din aplicația curentă poate fi obtainedby verificare require.main.filename.,

Addenda: Sfaturi pentru managerul de pachete#

semantica nodului.js require() funcția au fost proiectate pentru a fi generalenough pentru a sprijini structuri de director rezonabile. Package manager programssuch ca dpkg, rpm și npm va găsi, sperăm, este posibil să buildnative pachete din Nod.module js fără modificări.

mai jos oferim o structură de directoare sugerată care ar putea funcționa:

pachetele pot depinde unele de altele., În scopul de a instala pachetul foo, itmay fi necesar să instalați o versiune specifică a pachetului bar. barpachetul se poate avea dependențe, și, în unele cazuri, acestea pot chiar collideor forma ciclică dependențe.

deoarece nod.,js se uită în sus la realpath de orice module se încarcă (care este, itresolves legături simbolice) și apoi se uită pentru dependințele lor în node_modules foldere,această situație poate fi rezolvată cu următoarea arhitectură:

Astfel, chiar dacă un ciclu este întâlnit, sau dacă există dependencyconflicts, fiecare modul va fi capabil de a obține o versiune de dependencythat se poate folosi.

pentru a pune modulele la dispoziția nodului.js REPL, ar putea fi util toalso adaugă /usr/lib/node_modules folderul $NODE_PATH environmentvariable., Deoarece modulul căutări folosind node_modules foldere sunt allrelative, și se bazează pe cale reală de fișiere de a face apeluri larequire(), pachetele pot fi oriunde.

Addenda: la .extensia MJS#

nu este posibil să require() fișiere care au extensia.mjs.Încercarea de a face acest lucru va arunca o eroare. .mjs extensia isreserved pentru ECMAScript Module care pot fi încărcate prin require().A se vedea modulele ECMAScript pentru mai multe detalii.,

toate împreună…#

Pentru a obține exact numele fisierului care va fi încărcat atunci când require() este numit, usethe require.resolve() function.

de a Pune împreună toate cele de mai sus, aici este la nivel înalt algorithmin pseudocod de ce require() are:

Caching#

Module sunt memorate în cache, după prima dată când sunt încărcate. Acest lucru înseamnă (printre alte lucruri) că fiecare apel require('foo') va obține exact același objectreturned, dacă s-ar rezolva în același fișier.,

cu Condiția require.cache nu este modificat, mai multe apeluri la require('foo')nu va determina modulul de cod pentru a fi executat de mai multe ori. Aceasta este o caracteristică importantă. Cu aceasta, obiectele „parțial realizate” pot fi returnate, permițând astfel încărcarea dependențelor tranzitive chiar și atunci când ar provoca cicluri.

pentru a avea un modul executa codul de mai multe ori, exporta o funcție, și apel thatfunction.

avertismente de memorare în cache a modulelor #

modulele sunt memorate în cache pe baza numelui de fișier rezolvat., Deoarece modulele pot resolveto un nume de fișier diferit în funcție de locația de modulul de asteptare (loadingfrom node_modules foldere), aceasta nu este o garanție că require('foo') willalways reveni exact același obiect, dacă s-ar rezolva de la diferite fișiere.

în Plus, pe caz-insensibil sisteme de fișiere sau sisteme de operare, differentresolved nume de fișiere pot indica același fișier, dar cache-ul va mai treatthem ca diferite module și va reîncărca fișierul de mai multe ori., De exemplu,require('./foo') și require('./FOO') întoarcere două obiecte diferite,indiferent dacă sunt sau nu ./foo și ./FOO sunt același fișier.

module de bază #

nod.js are mai multe module compilate în binar. Aceste module sunt descrise mai detaliat în altă parte a acestei documentații.

modulele de bază sunt definite în cadrul nodului.sursa js și sunt localizate în folderullib/.,

modulele de bază sunt întotdeauna încărcate preferențial dacă identificatorul lor este trecut la require(). De exemplu, require('http') va întotdeaunareturnați modulul HTTP construit, chiar dacă există un fișier cu acest nume.

Cicluri#

atunci Când există circulară require() apeluri, un modul nu ar fi finishedexecuting atunci când este returnat.,

gândiți-vă această situație:

a.js:

b.js:

main.js:

console.log('main starting');const a = require('./a.js');const b = require('./b.js');console.log('in main, a.done = %j, b.done = %j', a.done, b.done);

main.js sarcini a.js, apoi a.js la rândul său sarcini b.js. La acel moment, b.js încearcă să încarce a.js. În scopul de a preveni o infiniteloop, un neterminat copie a a.js exporturilor obiect este returnatb.js module., b.js apoi, finisaje de încărcare, și exports obiect este asigurat la a.js module.

până când main.js a încărcat ambele module, ambele sunt terminate.Ieșirea din acest program va fi astfel:

$ node main.jsmain startinga startingb startingin b, a.done = falseb donein a, b.done = truea donein main, a.done = true, b.done = true

planificarea Atentă este necesară pentru a permite ciclic modul de dependențe pentru a workcorrectly în termen de o aplicație.

module de fișiere#

Dacă numele exact al fișierului nu este găsit, atunci nod.,js va încerca să încarce therequired nume cu a adăugat extensii: .js, .json, și în cele din urmă.node.

.js fișierele sunt interpretate ca JavaScript fișiere text, și .json fișiere areparsed ca fișiere text JSON. .node fișierele sunt interpretate ca compilat addonmodules încărcate cu process.dlopen().,

Fara un lider '/', './' sau '../' pentru a indica un fișier, modul musteither fi un modul de bază sau este încărcat dintr-un node_modules folder.

Dacă anumită cale nu există, require() va arunca o Error cucode proprietate setat la 'MODULE_NOT_FOUND'.,

foldere ca module#

este convenabil să organizați programe și biblioteci în autodirectoare și apoi să furnizați un singur punct de intrare acelor directoare.Există trei moduri în care un dosar poate fi trecut la require() Asan argument.

primul este de a crea un package.json fișierul în rădăcina folderului,care specifică un main module., Un exemplu package.json fișier mightlook ca aceasta:

{ "name" : "some-library", "main" : "./lib/some-library.js" }

Dacă acest lucru a fost într-un dosar în ./some-library, apoirequire('./some-library') ar încerca să încărcați./some-library/lib/some-library.js.

aceasta este gradul de conștientizare a package.json fișiere în nod.J. S.

dacă nu există un fișierpackage.json prezent în director sau dacă intrarea"main" lipsește sau nu poate fi rezolvată, atunci nod.,jswill încercarea de a încărca o index.js sau index.node fișier de thatdirectory. De exemplu, dacă nu a fost nici un package.json fișier în previousexample, apoi require('./some-library') ar încerca să se încarce:

• ./some-library/index.js
• ./some-library/index.node

Dacă aceste încercări eșuează, apoi Nod.,js va raporta întregul modul ca missingwith implicit de eroare:

Error: Cannot find module 'some-library'

Încărcare de node_modules foldere#

Dacă nu este găsit acolo, apoi se mută la directorul părinte, și, în curând, până la rădăcină al sistemului de fișiere este de ajuns.

• /home/ry/projects/node_modules/bar.js
• /home/ry/node_modules/bar.js
• /home/node_modules/bar.js
• /node_modules/bar.js

Aceasta permite programe pentru a localiza lor dependențe, astfel încât acestea să notclash.,

este posibil să se solicite fișiere specifice sau sub-module distribuite cu amodule prin includerea unui sufix de cale după numele modulului. De exemplurequire('example-module/path/to/file') ar rezolva path/to/filerelativ la cazul în care example-module este situat. Calea sufixată urmeazăaceeași semantică a rezoluției modulului.

Încărcare de dosare globale#

NODE_PATH variabila de mediu este setat la un colon delimitat listof căi absolute, atunci Nod.js va căuta acele căi pentru module dacă nu sunt găsite în altă parte.,

Pe Windows, NODE_PATH este delimitate prin punct și virgulă (;) în loc de două puncte.

NODE_PATH a fost inițial creat pentru a sprijini încărcare module fromvarying căi înainte de modulul curent rezoluție algoritm a fost definit.

NODE_PATH este încă acceptată, dar este mai puțin necesară acum că nodul.jsecosystem a stabilit o convenție pentru localizarea modulelor dependente.,Uneori implementările care se bazează pe NODE_PATH show surprinzător behaviorwhen oameni nu sunt conștienți că NODE_PATH trebuie să fie stabilite. Uneori amodule dependențele schimba, provocând o versiune diferită (sau chiar altă module) pentru a fi încărcate ca NODE_PATH este căutat.

În plus, nod.,js va căuta în următoarea listă de GLOBAL_FOLDERS:

• 1: $HOME/.node_modules
• 2: $HOME/.node_libraries
• 3: $PREFIX/lib/node

Unde $HOME este directorul home al utilizatorului, și $PREFIX este Nodul.jsconfigured node_prefix.acestea sunt în mare parte din motive istorice.

este încurajat să plasați dependențe în folderul local node_modules. Acestea vor fi încărcate mai repede și mai fiabil.,

modulul wrapper #

înainte de codul unui modul este executat, nod.js va încheia cu un functionwrapper care arată în felul următor:

(function(exports, require, module, __filename, __dirname) {// Module code actually lives in here});

Prin aceasta, Nodul.js realizează câteva lucruri:

• Se păstrează la nivel de top variabile (definite cu var, const sau let) luneta la modul mai degrabă decât de obiectul global.,
• ajută la furnizarea unor globală-în căutarea variabile care sunt de fapt specificto modulului, cum ar fi:
  • module și exports obiecte care implementeaza puteți utiliza pentru a exportvalues de la modul.
  • confortul variabile __filename și __dirname, care conține themodule absolută a fișierului și calea directorului.

domeniul de aplicare al modulului#

__dirname#

• <string>

numele directorului de modulul curent. Aceasta este aceeași cupath.dirname()din __filename.

Exemplu: rularea node example.js de la /Users/mjr

console.log(__dirname);// Prints: /Users/mjrconsole.log(path.dirname(__filename));// Prints: /Users/mjr

__filename#

• <string>

numele de fișier al modulului curent. Acesta este absolutepath fișierul modulului curent cu symlink-uri rezolvate.,

pentru un program principal, acest lucru nu este neapărat același cu numele fișierului utilizat înlinia de comandă.

A se vedea __dirname pentru numele directorului modulului curent.,

Examples:

Running node example.js from /Users/mjr

console.log(__filename);// Prints: /Users/mjr/example.jsconsole.log(__dirname);// Prints: /Users/mjr

Given two modules: a and b, where b is a dependency ofa and there is a directory structure of:

• /Users/mjr/app/a.js
• /Users/mjr/app/node_modules/b/b.js

exports#

• <Object>

O trimitere la module.exports care este mai scurt de tip.Consultați secțiunea despre comanda rapidă pentru exporturi pentru detalii despre când să utilizațiexportsși când să utilizați module.exports.

module#

• <modulul>

O referire la modul curent, consultați secțiunea despremodule obiect., In particular, module.exports is used for defining whata module exports and makes available through require().

require(id)#

• id <string> module name or path
• Returns: <any> exported module content

Used to import modules, JSON, and local files. Modules can be importedfrom node_modules., Locale, module și fișiere JSON pot fi importate usinga cale relativă (de exemplu ./, ./foo, ./bar/baz, ../foo) care va beresolved împotriva director numit prin __dirname (dacă a fost definită) sau director de lucru curent. Căile relative ale stilului POSIX sunt rezolvateîn mod independent de sistemul de operare, ceea ce înseamnă că exemplele de mai sus vor funcționa peWindows în același mod în care ar fi pe sistemele Unix.

require.cache#

• <Object>

Module sunt memorate în cache în acest obiect atunci când acestea sunt necesare. Prin ștergerea unei valori cheie din acest obiect, următorul require va reîncărca modulul.Acest lucru nu se aplică suplimentelor native, pentru care reîncărcarea va duce la anerror.

adăugarea sau înlocuirea intrărilor este de asemenea posibilă. Această memorie cache este bifată înaintemodule alternative și dacă un nume care se potrivește cu un modul nativ este adăugat în cache,nu este nevoie de apel pentru a primi modulul nativ mai. Utilizați cu grijă!,

require.extensions#

• <Object>

Instrui require pe cum să se ocupe de anumite extensii de fișiere.

Procesul fișiere cu extensia .sjs ca .js:

require.extensions = require.extensions;

Învechită. În trecut, această listă a fost utilizată pentru a încărca non-JavaScriptmodules în nod.js prin compilarea lor la cerere., Cu toate acestea, în practică, existăsunt modalități mult mai bune de a face acest lucru, cum ar fi încărcarea modulelor prin intermediul unui alt nod.jsprogram, sau compilarea lor la JavaScript înainte de timp.

evitați utilizarea require.extensions. Utilizarea ar putea provoca erori subtile și rezolvarea extensiilor devine mai lentă cu fiecare extensie înregistrată.

require.main#

• <modulul>

Module obiect reprezentând intrarea script încărcate atunci când Nodul.jsprocess lansat.,See „Accessing the main module”.

In entry.js script:

console.log(require.main);

node entry.js

require.resolve(request)#

• request <string> The module path to resolve.
• options <Object>
  • paths <string> Paths to resolve module location from., Dacă este prezent, thesepaths sunt folosite în loc de implicit rezoluția căi, cu exceptionof GLOBAL_FOLDERS ca $HOME/.node_modules, care sunt alwaysincluded. Fiecare dintre aceste căi este folosit ca un punct de plecare pentru modulul de rezoluție algoritm, ceea ce înseamnă că node_modules hierarchyis verificat din această locație.,
• se Întoarce: <string>

Utilizare internă require() utilaje pentru a căuta locația de un modul,dar, mai degrabă decât de încărcare modul, doar reveni rezolvate filename.

dacă modulul nu poate fi găsit, este aruncată o eroare MODULE_NOT_FOUND.

require.resolve.paths(request)#

• request <string> modulul calea cărui căutare căi sunt preluate.,
• Returns: <string> | <null>

Returns an array containing the paths searched during resolution of request ornull if the request string references a core module, for example http orfs.

The module object#

• <Object>

În fiecare modul, module gratuit variabilă este o referință la objectrepresenting modulul curent. Pentru comoditate, module.exportseste accesibil și prin modulul exports -global. module nu este de faptun global, ci mai degrabă local pentru fiecare modul.

modul.copii #

• <modulul>

modulul obiecte necesare pentru prima dată de către acesta.

modul.exporturile#

• <Object>

module.exports obiectul este creat de Module sistem. Uneori, acest lucru nu este acceptabil; mulți doresc ca modulul lor să fie o instanță a unei clase. Pentru a faceacest lucru, atribuiți obiectul de export dorit la module.exports., Assigningthe obiectul dorit să exports pur și simplu va rebind locale exports variabilă,care este, probabil, nu ceea ce este de dorit.

De exemplu, să presupunem că am face un modul numit a.js:

Apoi, într-un alt dosar am putea face:

const a = require('./a');a.on('ready', () => { console.log('module "a" is ready');});

Misiunea să module.exports trebuie să fie făcut imediat. Ea nu poate bedone în orice callback., Acest lucru nu funcționează:

x.js:

setTimeout(() => { module.exports = { a: 'hello' };}, 0);

y.js:

const x = require('./x');console.log(x.a);

exports shortcut#

exports variabila este disponibil într-un modul fișier la nivel de aplicare, și isassigned valoarea module.exports înainte modulul este evaluată.,

module.exports proprietatea este complet înlocuit cu un newobject, este comun pentru a, de asemenea, de a realoca exports:

module.exports = exports = function Constructor() { // ... etc.};

Pentru a ilustra comportamentul, imaginați-vă acest ipotetic punerea în aplicare arequire(), care este destul de similar cu ceea ce este, de fapt face prin require():

module.filename#

• <string>

pe deplin rezolvate de fișier al modulului.

modul.,id#

• <string>

identificatorul modulului. De obicei, aceasta este complet rezolvatănume de film.

modul.isPreloading#

• Tip: <boolean> true dacă modul de funcționare este în Nod.JS preloadphase.

modul.încărcat#

• <boolean>

Dacă este sau nu modulul este gata de încărcare, sau este în proces ofloading.

modul.părinte#

• <modulul> | <null> | <nedefinit>

Modulul necesar în primul rând asta, sau null dacă modul curent este theentry punct de procesul actual, sau undefined dacă modulul a fost încărcat bysomething că nu este un CommonJS module (E. G.: REPL sau import).

modul.cale#

• <string>

directorul numele modulului. Aceasta este de obicei aceeași cupath.dirname()din module.id.

modul.căi#

• <string>

căi de căutare pentru module.

modul.require (id)#

• id <string>
• se Întoarce: <orice> exportate module de conținut

module.require() metodă oferă o modalitate de a încărca un modul ca dacarequire() a fost numit de original module.pentru a face acest lucru, este necesar să obțineți o referință la obiectul module.,Deoarece require() returnează module.exports și module este typicallyonly disponibile într-un anumit modulul de cod, acesta trebuie să fie în mod explicit exportedin scopul de a fi utilizate.

obiectul modulului#

această secțiune a fost mutată toModules: module modulul de bază.

• module.builtinModules
• module.createRequire(filename)
• module.createRequireFromPath(filename)
• module.syncBuiltinESMExports()