Node.js v15.8.0 Documentación

En el Nodo.sistema de Módulos js, cada archivo se trata como un módulo separado. Por ejemplo, considere un archivo llamado foo.js:

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

En la primera línea, foo.js carga el módulo circle.js, que está en el samedirectory foo.js.,

Aquí está el contenido de circle.js:

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

El módulo circle.js ha exportado sus funciones area() ycircumference(). Las funciones y los objetos se añaden a la raíz de un moduleby especificando propiedades adicionales en el objeto especial exports.

Las Variables locales al módulo serán privadas, porque el módulo está envuelto en una función por nodo.en este ejemplo, la variable PI es privada para circle.js.,

a la propiedad module.exports se le puede asignar un nuevo valor (como un objeto functionor).

a Continuación, bar.js hace uso de la etiqueta square módulo, que las exportaciones de una Plaza de clase:

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

El square módulo se define en square.js:

El módulo del sistema se implementa en el require('module') módulo.

acceder al módulo principal#

Cuando un archivo se ejecuta directamente desde el nodo.js, require.main se establece en su module., Eso significa que es posible determinar si un archivo se ha ejecutado directamente probando require.main === module.

De un archivo foo.js, esto será true si se ejecuta a través de node foo.js, perofalse si se ejecuta por require('./foo').

dado que module proporciona una propiedad filename (normalmente equivalente a__filename), el punto de entrada de la aplicación actual se puede obtener marcando require.main.filename.,

Addenda: Package manager tips#

la semántica del nodo.la función JS require() fue diseñada para ser lo suficientemente general como para soportar estructuras de directorios razonables. Los programas del gestor de paquetes como dpkg, rpm, y npm encontrarán con suerte que es posible compilar paquetes desde el nodo.módulos js sin modificación.

a continuación le damos una estructura de directorios sugerida que podría funcionar:

Los paquetes pueden depender unos de otros., Para instalar el paquete foo, puede ser necesario instalar una versión específica del paquete bar. El paquete barpuede tener dependencias, y en algunos casos, estas pueden incluso colisionar o formar dependencias cíclicas.

Porque Nodo.,js busca los realpath de cualquier módulo que cargue (es decir, resuelve enlaces simbólicos) y luego busca sus dependencias en las carpetas node_modules, esta situación se puede resolver con la siguiente arquitectura:

así, incluso si se encuentra un ciclo, o si hay dependencyconflicts, cada módulo podrá obtener una versión de su dependencia que puede usar.

para poner los módulos a disposición del nodo.JS REPL, también podría ser útil agregar la carpeta /usr/lib/node_modules a la variable de entorno $NODE_PATH., Dado que las búsquedas de módulos usando carpetas node_modules son allrelative, y basadas en la ruta real de los archivos que hacen las llamadas arequire(), los paquetes pueden estar en cualquier lugar.

Addenda: The .extensión mjs #

no es posible require() archivos que tengan la extensión .mjs.Intentar hacerlo arrojará un error. La extensión .mjs se conserva para los módulos ECMAScript que no se pueden cargar a través de require().Vea módulos ECMAScript para más detalles.,

Todos juntos…#

para obtener el nombre de archivo exacto que se cargará cuando se llame a require(), utilice la función require.resolve().

juntando todo lo anterior, Aquí está el pseudocódigo algorítmico de alto nivel de lo querequire() hace:

Caching#

Los módulos se almacenan en caché después de la primera vez que se cargan. Esto significa (entre otras cosas) que cada llamada a require('foo') obtendrá exactamente el mismo objectreturned, si se resuelve en el mismo archivo.,

siempre que require.cache no se modifique, las llamadas múltiples a require('foo')no harán que el código del módulo se ejecute varias veces. Esta es una característica importante. Con él, se pueden devolver objetos» parcialmente realizados», permitiendo así que las dependencias transitivas se carguen incluso cuando causen ciclos.

para que un módulo ejecute código varias veces, exporte una función y llame a thatfunction.

advertencias de almacenamiento en caché de Módulos#

Los módulos se almacenan en caché en función de su nombre de archivo resuelto., Dado que los módulos pueden resolver a un nombre de archivo diferente basado en la ubicación del módulo que llama (loadingfrom node_modules carpetas), no es una garantía de que require('foo') siempre devolverá el mismo objeto exacto, si se resolvería a diferentes archivos.

Además, en sistemas de archivos o sistemas operativos que no distinguen entre mayúsculas y minúsculas, los diferentes nombres de archivo resueltos pueden apuntar al mismo archivo, pero la caché seguirá tratándolos como módulos diferentes y recargará el archivo varias veces., Por ejemplo,require('./foo') y require('./FOO') retorno de dos objetos diferentes,independientemente de si o no ./foo y ./FOO son el mismo archivo.

core modules #

Node.js tiene varios módulos compilados en el binario. Estos módulos se describen con mayor detalle en otra parte de esta documentación.

los módulos principales se definen dentro del nodo.fuente js y se encuentran en la carpetalib/.,

Los módulos principales siempre se cargan preferentemente si su identificador se pasa a require(). Por ejemplo, require('http') siempre devolverá el módulo HTTP incorporado, incluso si hay un archivo con ese nombre.

Cycles#

Cuando hay llamadas circularesrequire(), es posible que un módulo no tenga finishedexecuting cuando se devuelve.,

Considere esta situación:

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

Cuando main.js carga a.js, luego a.js a su vez carga b.js. En thatpoint, b.js intenta cargar a.js. Para evitar un infiniteloop, una copia inacabada del objeto a.js exports se devuelve al módulob.js., b.jsluego termina de cargarse, y su objeto exportsse proporciona al módulo a.js.

en el momento en que main.js ha cargado ambos módulos, ambos están terminados.La salida de este programa sería:

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

se requiere una planificación cuidadosa para permitir que las dependencias de Módulos cíclicos funcionen correctamente dentro de una aplicación.

módulos de archivo #

Si no se encuentra el nombre de archivo exacto, entonces Node.,js intentará cargar el nombre de archivo requerido con las extensiones añadidas: .js, .json, y finalmente.node.

.js los archivos se interpretan como archivos de texto JavaScript, y .json los archivos se comparan como archivos de texto JSON. .node los archivos se interpretan como módulos de complemento compilados cargados con process.dlopen().,

Sin un líder '/', './' o '../' para indicar un archivo, el módulo de musteither ser un módulo principal o se cargan de un node_modules carpeta.

Si la ruta no existe, require() lanzará un Error sucode hotel 'MODULE_NOT_FOUND'.,

carpetas como módulos#

es conveniente organizar programas y bibliotecas en directorios autocontenidos, y luego proporcionar un único punto de entrada a esos directorios.Hay tres formas en las que una carpeta se puede pasar a require() argumento asan.

la primera es crear un archivo package.json en la raíz de la carpeta,que especifica un módulo main., Un ejemplo package.json archivo mightlook como esto:

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

Si este estaba en una carpeta en el ./some-library, luegorequire('./some-library') intente cargar./some-library/lib/some-library.js.

Este es el alcance de la conciencia de package.json archivos dentro del nodo.js.

si no hay un archivo package.json presente en el directorio, o si la entrada"main" falta o no se puede resolver, entonces Node.,jswill intentará cargar un archivo index.js o index.node de thatdirectory. Por ejemplo, si no hay un package.json en el archivo de previousexample, entonces require('./some-library') intentaría carga:

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

Si todos los intentos fallan, luego Nodo.,js reportará todo el módulo como perdido con el error predeterminado:

Error: Cannot find module 'some-library'

Cargando desde las carpetas node_modules#

Si no se encuentra allí, entonces se mueve al directorio padre, y pronto, hasta que se alcance la raíz del sistema de archivos.

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

Esto permite que los programas para localizar a sus dependencias, por lo que no hacen notclash.,

es posible requerir archivos o módulos específicos distribuidos con amodule incluyendo un sufijo de Ruta después del nombre del módulo. Por ejemplorequire('example-module/path/to/file') resolvería path/to/filerelativo a donde example-module se encuentra. La ruta sufijada sigue la misma semántica de resolución del módulo.

Cargando desde las carpetas globales#

si la variable de entornoNODE_PATH se establece en una lista delimitada por dos puntos de rutas absolutas, entonces nodo.js buscará esas rutas para los módulos si no se encuentran en otro lugar.,

en Windows, NODE_PATH está delimitado por punto y coma (;) en lugar de dos puntos.

NODE_PATH se creó originalmente para soportar la carga de Módulos desde rutas variables antes de que se definiera el algoritmo de resolución del módulo actual.

NODE_PATH sigue siendo compatible, pero es menos necesario Ahora que el nodo.jsecosystem ha establecido una convención para localizar módulos dependientes.,A veces, las implementaciones que dependen de NODE_PATH muestran un comportamiento sorprendente cuando las personas no saben que se debe establecer NODE_PATH. A veces las dependencias de amodule cambian, causando que se cargue una versión diferente (o incluso un módulo diferente) mientras se busca NODE_PATH.

Además, Node.,js busca en la siguiente lista de GLOBAL_FOLDERS:

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

Donde $HOME es el directorio home del usuario, y $PREFIX es el Nodo.jsconfigured node_prefix.

Estos son principalmente por razones históricas.

Se recomienda encarecidamente colocar dependencias en la carpeta local node_modules. Estos se cargarán más rápido y de manera más confiable.,

el envoltorio del módulo #

antes de que se ejecute el código de un módulo, nodo.js lo envolverá con un functionwrapper que se parece a lo siguiente:

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

haciendo esto, Node.js logra algunas cosas:

• mantiene las variables de nivel superior (definidas con var, consto let) dentro del ámbito del módulo en lugar del objeto global.,
• ayuda a proporcionar algunas variables de aspecto global que son realmente específicas para el módulo, tales como:
  • Los Objetos moduley exports que el implementador puede usar para exportar valores desde el módulo.
  • Las variables de conveniencia __filenamey __dirname, que contienen el nombre de archivo absoluto del módulo y la ruta del directorio.

El ámbito de módulo#

__dirname#

• <string>

el directorio en El nombre del módulo actual. Este es el mismo que elpath.dirname() del __filename.

Ejemplo: la ejecución de node example.js de /Users/mjr

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

__nombre de archivo#

• <string>

El nombre de archivo del módulo actual. Esta es la ruta absoluta del archivo del módulo actual con los enlaces simbólicos resueltos.,

para un programa principal esto no es necesariamente el mismo que el nombre de archivo utilizado en la línea de comandos.

vea __dirname para el nombre del directorio del módulo actual.,

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#

• <Objeto>

Una referencia a la etiqueta module.exports que es más corto.Consulte la sección sobre el acceso directo de exportaciones para obtener detalles sobre cuándo usarexports y cuándo usar module.exports.

módulo#

• <módulo>

Una referencia para el módulo actual, consulte la sección sobre elmodule objeto., 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., Los módulos locales y los archivos JSON se pueden importar usando una ruta relativa (por ejemplo, ./, ./foo, ./bar/baz, ../foo) que se resolverá contra el directorio»37cb4c381e»> (si está definido) o el directorio de trabajo actual. Las rutas relativas del estilo POSIX se resuelven de manera independiente del sistema operativo, lo que significa que los ejemplos anteriores funcionarán en ventanas de la misma manera que lo harían en sistemas Unix.

require.cache#

• <Objeto>

los Módulos se almacenan en este objeto cuando son requeridos. Al eliminar un valor clave de este objeto, el siguiente require recargará el módulo.Esto no se aplica a los complementos nativos, para los que la recarga resultará en anerror.

Agregar o reemplazar entradas también es posible. Esta caché se comprueba antes de los módulos nativos y si se agrega un nombre que coincida con un módulo nativo a la caché,ya no se va a recibir la llamada require del módulo nativo. ¡Úsalo con cuidado!,

require.extensions#

• <Objeto>

Instruir require acerca de cómo manejar determinadas extensiones de archivo.

el Proceso de los archivos con la extensión .sjs .js:

require.extensions = require.extensions;

en Desuso. En el pasado, esta lista se ha utilizado para cargar módulos no-JavaScriptmodules en el nodo.js compilándolos bajo demanda., Sin embargo, en la práctica, hay formas mucho mejores de hacerlo, como cargar módulos a través de algún otro nodo.jsprogram, o compilarlos a JavaScript antes de tiempo.

evite usar require.extensions. El uso podría causar errores sutiles y la resolución de las extensiones se vuelve más lenta con cada extensión registrada.

require.main#

• <módulo>

El Module objeto que representa la entrada de secuencia de comandos de carga cuando el Nodo.jsprocess lanzado.,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., Si están presentes, estas rutas se utilizan en lugar de las rutas de resolución predeterminadas, con la excepción de GLOBAL_FOLDERS como $HOME/.node_modules, que siempre están incluidas. Cada una de estas rutas se utiliza como punto de partida para el algoritmo de resolución del módulo, lo que significa que la jerarquía node_modules se comprueba desde esta ubicación.,
• Devuelve: <string>

los require() maquinaria para buscar la ubicación de un módulo,pero en lugar de cargar el módulo, acabo de volver de las resueltos nombre de archivo.

si el módulo no se puede encontrar, se lanza un error MODULE_NOT_FOUND.

require.resolve.paths(request)#

• request <string> La ruta de acceso del módulo cuya búsqueda de caminos se recuperan.,
• 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>

en cada módulo, la variable libre module es una referencia al objectrepresentando el módulo actual. Para mayor comodidad, module.exportstambién es accesible a través del módulo exports -global. module no es realmente global sino local para cada módulo.módulo

.niños #

• <módulo>

El módulo de objetos necesarios para la primera vez por este.módulo

.las exportaciones de#

• <Objeto>

El module.exports objeto es creado por el Module sistema. A veces esto no es aceptable; muchos quieren que su módulo sea una instancia de alguna clase. Para ello, asigne el objeto de exportación deseado a module.exports., Asignar el objeto deseado a exports simplemente volverá a enlazar la variable local exports, que probablemente no es lo que se desea.

por ejemplo, supongamos que estábamos haciendo un módulo llamado a.js:

entonces en otro archivo podríamos hacer:

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

la asignación a module.exports debe hacerse inmediatamente. No se puede hacer en ninguna devolución de llamada., Esto no funciona:

x.js:

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

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

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