Node.js V15.8. 0 Documentation

dans le nœud.système de module js, chaque fichier est traité comme un module séparé. Par exemple, considérons un fichier nommé foo.js:

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

Sur la première ligne, foo.js charge le module circle.js qui est dans le samedirectory foo.js.,

Voici le contenu de la balise circle.js:

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

Le module circle.js a exporté les fonctions area() etcircumference(). Les fonctions et les objets sont ajoutés à la racine d’un module en spécifiant des propriétés supplémentaires sur l’objet spécial exports.

Les Variables locales au module seront privées, car le module est encapsulé dans une fonction par nœud.dans cet exemple, la variable PI est privée à circle.js.,

la propriétémodule.exports peut recevoir une nouvelle valeur (comme un objet functionor).

ci-Dessous, bar.js rend l’utilisation de la balise square module, qui exporte un Carré de la classe:

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

Le square module est définie dans square.js:

Le module système est mis en œuvre dans le require('module') module.

Accès au module principal#

Lorsqu’un fichier est exécuté directement à partir du Nœud.js, require.main est défini à samodule., Cela signifie qu’il est possible de déterminer si un fichier a été exécuté directement en testant require.main === module.

Pour un fichier foo.js ce sera true si elle est exécutée à l’aide de node foo.js, maisfalse s’il est exécuté par require('./foo').

étant donné quemodule fournit une propriétéfilename (normalement équivalente à__filename), le point d’entrée de l’application actuelle peut être obtenu en vérifiantrequire.main.filename.,

Addenda: conseils du Gestionnaire de paquets#

la sémantique du nœud.la fonction js require() a été conçue pour être assez générale pour prendre en charge des structures de répertoires raisonnables. Les programmes du gestionnaire de paquets tels que dpkg, rpm Et npm trouveront, espérons-le, la possibilité de construire des paquets natifs à partir du nœud.modules js sans modification.

ci-dessous, nous donnons une structure de répertoire suggérée qui pourrait fonctionner:

Les paquets peuvent dépendre les uns des autres., Afin d’installer le paquet foo, itmay être nécessaire d’installer une version spécifique de paquet bar. Le package barpeut lui-même avoir des dépendances, et dans certains cas, celles-ci peuvent même entrer en collision ou former des dépendances cycliques.

Car Nœud.,js recherche les realpath de tous les modules qu’il charge (c’est-à-dire qu’il résout les liens symboliques) puis Recherche leurs dépendances dans les dossiers node_modules, cette situation peut être résolue avec l’architecture suivante:

ainsi,même si un cycle est rencontré, ou s’il dependencythat il peut utiliser.

afin de rendre les modules disponibles au nœud.js REPL, il peut être utile d’ajouter également le dossier/usr/lib/node_modules à la variable d’environnement$NODE_PATH., Étant donné que les recherches de modules utilisant les dossiersnode_modules sont toutes relatives et basées sur le chemin réel des fichiers faisant les appels àrequire(), les paquets eux-mêmes peuvent être n’importe où.

Addenda: le .mjs extension#

Il n’est pas possible de require() fichiers qui ont le .mjs extension.Tenter de le faire génère une erreur. L’extension.mjs est réservée aux Modules ECMAScript qui ne peuvent pas être chargés viarequire().Voir modules ECMAScript pour plus de détails.,

Tous ensemble…#

pour obtenir le nom de fichier exact qui sera chargé lorsquerequire()est appelé, utilisez la fonctionrequire.resolve().

en rassemblant tout ce qui précède, voici le pseudocode algorithmin de haut niveau de ce querequire() fait:

Caching#

Les Modules sont mis en cache après la première fois qu’ils sont chargés. Cela signifie (entre autres) que chaque appel à require('foo') obtiendra exactement le même objectreturned, s’il se résolvait dans le même fichier.,

à condition querequire.cache ne soit pas modifié, les appels multiples àrequire('foo')ne provoquent pas l’exécution du code du module plusieurs fois. C’est animportant fonctionnalité. Avec lui, les objets « partiellement faits » peuvent être retournés, permettant ainsi aux dépendances transitives d’être chargées même lorsqu’elles provoqueraient des cycles.

pour qu’un module exécute du code plusieurs fois, exporte une fonction et appelle thatfunction.

mise en cache des modules#

Les Modules sont mis en cache en fonction de leur nom de fichier résolu., Étant donné que les modules peuvent résoudre un nom de fichier différent en fonction de l’emplacement du module appelant (dossiers loadingfrom node_modules), il n’est pas garanti que require('foo') retournera toujours exactement le même objet, s’il se résolvait dans des fichiers différents.

de plus, sur les systèmes de fichiers ou les systèmes d’exploitation insensibles à la casse, différents noms de fichiers résolus peuvent pointer vers le même fichier, mais le cache les traitera toujours comme des modules différents et rechargera le fichier plusieurs fois., Par exemple, la baliserequire('./foo') et require('./FOO') le retour de deux objets différents,indépendamment de si oui ou non ./foo et ./FOO sont le même fichier.

des modules de Base#

Nœud.js a plusieurs modules compilés dans le binaire. Ces modules sont décrits plus en détail ailleurs dans cette documentation.

les modules principaux sont définis dans le nœud.js source et sont situés dans le dossierlib/.,

les modules de base sont toujours chargés préférentiellement si leur identifiant est passé àrequire(). Par exemple, require('http') retournera toujours le module HTTP intégré, même s’il existe un fichier de ce nom.

Cycles#

Lorsqu’il y a des appels circulairesrequire(), un module peut ne pas avoir finishedexecuting lorsqu’il est renvoyé.,

de Considérer cette situation:

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);

Lors de la main.js charges a.js, puis a.js charge à son tour b.js. À ce point, b.js tente de charger a.js. Afin d’éviter une infiniteloop, une copie inachevée de l’objet a.js exports est renvoyée au moduleb.js., b.js termine alors le chargement, et son objet exports est fourni au module a.js.

au moment oùmain.js a chargé les deux modules, ils sont tous deux terminés.La sortie de ce programme serait donc:

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

une planification minutieuse est nécessaire pour permettre aux dépendances de modules cycliques de fonctionner correctement dans une application.

Fichier modules#

Si le nom de fichier exact n’est pas trouvée, alors le Nœud.,js tentera de charger le nom de fichier requis avec les extensions ajoutées: .js, .json, et enfin.node.

.js les fichiers sont interprétés comme JavaScript et les fichiers texte .json fichiers areparsed JSON fichiers texte. .node les fichiers sont interprétés comme des modules complémentaires compilés chargés avec process.dlopen().,

Sans '/', './' ou '../' pour indiquer un fichier, le module musteither être un module de base ou chargées à partir d’une node_modules dossier.

Si le chemin n’existe pas, require() va jeter un Error avec sacode propriété a la valeur 'MODULE_NOT_FOUND'.,

dossiers sous forme de modules#

Il est pratique d’organiser les programmes et les bibliothèques dans des répertoires auto-contenués, puis de fournir un point d’entrée unique à ces répertoires.Il existe trois façons de transmettre un dossier à require() en tant qu’argument asan.

la première consiste à créer un fichier package.jsonà la racine du dossier,qui spécifie un module main., Un exemple: package.json fichier mightlook comme ceci:

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

Si c’était dans un dossier ./some-library, puisrequire('./some-library') serait tenter de charger./some-library/lib/some-library.js.

c’est l’étendue de la prise de conscience des fichierspackage.json dans Node.js.

S’il n’y a pas de fichierpackage.json présent dans le répertoire, ou si l’entrée"main" est manquante ou ne peut pas être résolue, alors Node.,jswill tentative de chargement d’un index.js ou index.node fichier de thatdirectory. Par exemple, si il n’y a pas de package.json fichier dans le previousexample, puis require('./some-library') serait tenter de charge:

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

Si ces tentatives échouent, alors Nœud.,js signalera le module entier comme manquantavec l’erreur par défaut:

Error: Cannot find module 'some-library'

chargement à partir des dossiers node_modules#

s’il n’y est pas trouvé, il se déplace vers le répertoire parent, et bientôt, jusqu’à ce que la racine du système de fichiers soit atteinte.

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

Cela permet aux programmes de localiser leurs dépendances, de sorte qu’ils ne notclash.,

Il est possible d’exiger des fichiers ou des sous-modules spécifiques distribués avec amodule en incluant un suffixe de chemin après le nom du module. Par exemple:require('example-module/path/to/file') permettrait de résoudre path/to/filepar rapport à example-module est situé. Le chemin suffixé suit la même sémantique de résolution de module.

chargement à partir des dossiers globaux#

Si la variable d’environnementNODE_PATH est définie sur une liste de chemins absolus délimités par deux points, alors Node.js recherchera ces chemins pour les modules s’ils ne sont pas trouvés ailleurs.,

sous Windows, NODE_PATH est délimitée par des points-virgules (;) au lieu de deux points.

NODE_PATH a été créé à l’origine pour prendre en charge le chargement de modules à partir de chemins variables avant que l’algorithme de résolution de module actuel ne soit défini.

NODE_PATH est toujours pris en charge, mais est moins nécessaire maintenant que le nœud.jsecosystem a établi une convention pour localiser les modules dépendants.,Parfois, les déploiements qui reposent sur NODE_PATH montrent un comportement surprenant lorsque les gens ignorent que NODE_PATH doivent être définis. Parfois, les dépendances d’amodule changent, provoquant le chargement d’une version différente (ou même d’un module différent) lorsque le NODE_PATH est recherché.

en Outre, Nœud.,js va chercher dans la liste suivante de GLOBAL_FOLDERS:

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

Où $HOME est le répertoire home de l’utilisateur, et $PREFIX est le Nœud.jsconfigured node_prefix.

Ce sont surtout pour des raisons historiques.

Il est fortement recommandé de placer les dépendances dans le dossier localnode_modules. Ceux-ci seront chargés plus rapidement et de manière plus fiable.,

le wrapper de module#

avant l’exécution du code d’un module, Node.js va l’envelopper avec un functionwrapper qui ressemble à ceci:

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

En faisant cela, Nœud.js réalise quelques choses:

• Il conserve les variables de niveau supérieur (définies avec var, const ou let) étendues au module plutôt qu’à l’objet global.,
• Il permet de fournir des variables globales qui sont réellement spécifiques au module, telles que:
  • Les objetsmoduleEtexports que l’implémenteur peut utiliser pour exporter des valeurs à partir du module.
  • Les variables de commodité__filenameEt__dirname, contenant le nom de fichier absolu et le chemin du répertoire de themodule.

La portée de module#

__dirname#

• <string>

Le nom du répertoire du module en cours. C’est le même que lepath.dirname() de la __filename.

Exemple: courir node example.js à partir de /Users/mjr

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

__nom de fichier#

• <string>

Le nom de fichier du module en cours. C’est absolutepath du fichier module actuel avec des liens symboliques résolus.,

Pour un programme principal ce n’est pas nécessairement le même que le nom de fichier utilisé dans thecommand ligne.

Voir__dirname pour le nom de répertoire du module courant.,

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#

• <Objet>

Une référence à la balise module.exports c’est plus court à taper.Voir la section sur les exportations de raccourci pour plus de détails sur quand utiliserexports et quand utiliser des module.exports.

module#

• <le module>

Une référence à l’actuel module, reportez-vous à la section à propos de la balisemodule objet., 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., Les modules locaux et les fichiers JSON peuvent être importés en utilisant un chemin relatif (par exemple ./, ./foo, ./bar/baz, ../foo) qui sera résolu par rapport au répertoire nommé par __dirname (si défini) oule répertoire de travail actuel. Les chemins relatifs du style POSIX sont résolus de manière indépendante du système d’exploitation, ce qui signifie que les exemples ci-dessus fonctionneront sur Windows de la même manière que sur les systèmes Unix.

require.cache#

• <Objet>

les Modules sont mis en cache dans cet objet lorsqu’ils sont requis. En supprimant une valeur de clé de cet objet, le prochain require rechargera le module.Cela ne s’applique pas aux addons natifs, pour lesquels le rechargement entraînera une erreur.

L’ajout ou le remplacement d’entrées est également possible. Ce cache est vérifié avant les modules natifs et si un nom correspondant à un module natif est ajouté au cache,aucun appel require n’est plus nécessaire pour recevoir le module natif. À utiliser avec précaution!,

require.extensions#

• <Objet>

Charger require sur la façon de gérer certaines extensions de fichier.

Processus fichiers avec l’extension .sjs .js:

require.extensions = require.extensions;

Obsolète. Dans le passé, cette liste a été utilisée pour charger des non-JavaScriptmodules dans Node.js en les compilant à la demande., Cependant, en pratique, il y a de bien meilleurs moyens de le faire, tels que le chargement de modules via un autre nœud.jsprogram, ou les compiler en JavaScript à l’avance.

Évitez d’utiliser des require.extensions. L’utilisation pourrait provoquer des bogues subtils et la résolution des extensions devient plus lente avec chaque extension enregistrée.

require.main#

• <le module>

Le Module objet représentant l’entrée de script chargé lorsque le Nœud.jsprocess lancé.,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., S’ils sont présents, ces chemins sont utilisés à la place des chemins de résolution par défaut, à l’exception des fichiers GLOBAL_FOLDERS comme $HOME/.node_modules, qui sont toujours inclus. Chacun de ces chemins est utilisé comme point de départ pourl’algorithme de résolution du module, ce qui signifie que la hiérarchie node_modules est vérifiée à partir de cet emplacement.,
• Renvoie: <string>

Utilisation de la fonction interne require() machines afin de trouver l’emplacement d’un module,mais plutôt que de charger le module, il suffit de retourner l’résolu nom de fichier.

Si le module est introuvable, une erreurMODULE_NOT_FOUND est déclenchée.

require.resolve.paths(request)#

• request <string> Le chemin d’accès du module de recherche dont les chemins sont en cours de récupération.,
• 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#

• <Objet>

Dans chaque module, le module free variable est une référence à la objectrepresenting le module en cours. Pour plus de commodité, module.exports est également accessible via le module exports-global. module n’est pas réellement global mais plutôt local pour chaque module.

module.enfants #

• <le module>

Le module d’objets requis pour la première fois par celui-ci.

module.les exportations#

• <Objet>

Le module.exports objet est créé par la balise Module système. Parfois, ce n’est pas acceptable; beaucoup veulent que leur module soit une instance d’une classe. Pour ce faire, affectez l’objet d’exportation souhaité À module.exports., Assigningthe objet désiré à exports reliera simplement la variable locale exports, ce qui n’est probablement pas ce qui est souhaité.

Par exemple, supposons que nous avons été faire un module appelé a.js:

Ensuite, dans un autre fichier que nous avons pu faire:

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

Cession de module.exports doit être fait immédiatement. Il ne peut pas être utilisé dans les rappels., Cela ne fonctionne pas:

x.js:

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

y.js:

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

exports raccourci#

Le exports variable est disponible dans un fichier du module au niveau de la portée, et isassigned la valeur de module.exports avant que le module est évalué.,

Lors de la module.exports propriété est d’être complètement remplacé par un newobject, il est fréquent également de réaffecter exports:

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

Pour illustrer le comportement, imaginez ce hypothétique mise en œuvre derequire(), ce qui est assez similaire à ce qui est réellement fait par require():

module.nom de fichier#

• <string>

L’complètement résolu le nom de fichier du module.

module.,id#

• <string>

L’identifiant du module. Il s’agit généralement du nom de fichier entièrement résolu.

module.isPreloading#

• Type: <boolean> true si le module est en cours d’exécution pendant le Nœud.js preloadphase.

module.chargé#

• <boolean>

Si le module est fait, le chargement, ou est en train ofloading.

module.parent #

• <le module> | <null> | <undefined>

Le module d’abord, celui-ci, ou null si le module est theentry de l’actuel processus, ou undefined si le module a été chargé bysomething qui n’est pas un CommonJS module (E. G.: REPL ou import).

module.chemin#

• <string>

Le nom du répertoire du module. C’est généralement le même que lepath.dirname() de la module.id.

module.les chemins de#

• <string>

Les chemins de recherche pour le module.

module.besoin(id)#

• id <string>
• Renvoie: <tout> exporté contenu du module

Le module.require() méthode fournit un moyen pour charger un module comme sirequire() a été appelé à partir du module d’origine.

pour ce faire, il est nécessaire d’obtenir une référence à la balise module objet.,Étant donné que require() renvoie le module.exports, et que le module n’est généralement disponible que dans le code d’un module spécifique, il doit être exporté explicitement pour être utilisé.

l’objet Module#

Cette section a été déplacée versodules:module module de base.

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