Node.js V15.8. 0 documentação

no nó.sistema de módulos js, cada arquivo é tratado como um módulo separado. Forexample, considere um arquivo chamado foo.js:

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

Na primeira linha, foo.js carrega o módulo circle.js que está no samedirectory foo.js.,

Aqui o conteúdo de circle.js:

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

O módulo circle.js exportou as funções area() ecircumference(). Funções e objetos são adicionados à raiz de um moduleby especificando propriedades adicionais no especial exports objeto.

as variáveis locais ao módulo serão privadas, porque o módulo é wrappedin uma função por nó.js(ver invólucro do módulo). neste exemplo, a variável PI é privada a circle.js.,

a propriedademodule.exports pode ser atribuída um novo valor (tal como um objecto ou função).

Abaixo bar.js faz uso de square módulo, que as exportações de um Quadrado classe:

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

square módulo é definido no square.js:

O módulo do sistema é implementado require('module') módulo.

acessando o módulo principal#

quando um arquivo é executado diretamente do nó.js, require.mainé definido como seumodule., Isso significa que é possível determinar se um arquivo foi executado diretamente testando require.main === module.

Para um arquivo foo.js, este será true se o executado através de node foo.js, masfalse se executado por require('./foo').

Porque module fornece uma filename propriedade (normalmente equivalente a__filename), o ponto de entrada do aplicativo atual pode ser obtainedby verificar require.main.filename.,

Addenda: Package manager tips#

The semantics of the Node.a função js require() foi concebida para ser genérica o suficiente para suportar estruturas de diretórios razoáveis. O gerenciador de pacotes programssuch dpkg rpm e npm espero encontrá-lo possível para buildnative pacotes do Nó.módulos js sem modificação.

abaixo apresentamos uma estrutura de diretório sugerida que pode funcionar: os pacotes

podem depender uns dos outros., Para instalar o pacote foo, itmay ser necessário instalar uma versão específica do pacote bar. O pacote barpode ter dependências, e em alguns casos, estas podem até colidir ou formar dependências cíclicas.

porque nó.,js procura o realpath de todos os módulos que ele carrega (que é, itresolves links simbólicos) e, em seguida, olha para as suas dependências em node_modules pastas,esta situação pode ser resolvida com a seguinte arquitetura:

Assim, mesmo se um ciclo é encontrado, ou se há dependencyconflicts, cada módulo será capaz de obter uma versão de seu dependencythat ele pode usar.

a fim de disponibilizar módulos para o nó.js REPL, it might be useful toalso add the /usr/lib/node_modules folder to the $NODE_PATH environmentvariable., Uma vez que as pesquisas de módulos usando node_modules pastas são allrelativas, e com base no caminho real dos arquivos fazendo as chamadas pararequire(), os próprios pacotes podem estar em qualquer lugar.

Addenda: The .MJS extension#

It is not possible to require() files that have the .mjs extension.Tentar fazê-lo irá lançar um erro. The .mjs extension iserved for ECMAScript Modules which cannot be loaded via require().Veja os módulos ECMAScript para mais detalhes.,todos juntos…#

Para obter o nome exato do arquivo que será carregado quando require() é chamado, usethe require.resolve() função.

colocando todos OS acima, aqui está o pseudocódigo algorítmico de alto nível do querequire() faz:

Caching#

módulos são cache após a primeira vez que eles são carregados. Isto significa (entre outras coisas) que cada chamada para require('foo') vai obter exatamente o mesmo objetivo corrigido, se ele iria resolver para o mesmo arquivo.,

desde que require.cachenão seja modificado, múltiplas chamadas para require('foo') não fará com que o código do módulo seja executado várias vezes. Esta é uma característica importante. Com isso, objetos “parcialmente feitos” podem ser devolvidos, permitindo assim que dependências transitivas sejam carregadas mesmo quando causariam ciclos.

ter um módulo executar código várias vezes, exportar uma função, e chamar essa função.os módulos de cache de módulos#

são acoplados com base em seu nome de arquivo resolvido., Desde módulos podem resolveto um nome de arquivo diferente, com base na localização do módulo de chamada (loadingfrom node_modules pastas), ele não é uma garantia de que require('foo') willalways devolver exactamente o mesmo objeto, se iria resolver a diferentes arquivos.

adicionalmente, em sistemas de ficheiros ou sistemas operativos sem distinção de maiúsculas ou minúsculas, nomes de ficheiros diferentes podem apontar para o mesmo ficheiro, mas a ‘cache’ continuará a tratá-los como módulos diferentes e irá recarregar o ficheiro várias vezes., Por exemplo,require('./foo') e require('./FOO') retorno de dois objetos diferentes,independentemente da existência ou não de ./foo e ./FOO são o mesmo arquivo.

módulos de base#

nó.js tem vários módulos compilados no binário. Estes módulos são descritos em maior pormenor noutra parte desta documentação.

os módulos principais são definidos dentro do nó.js source and are located in thelib/ folder.,

os módulos de base são sempre carregados preferencialmente se o seu identificador for atribuído a require(). Por exemplo, require('http') irá sempre reverter o módulo HTTP construído, mesmo que exista um arquivo com esse nome.

ciclos#

quando existem circulares require() chamadas, um módulo pode não ter finalizado a execução quando é devolvido.,

Considere esta situação:

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

Quando main.js carrega a.js, então a.js por sua vez, carrega b.js. At thatpoint, b.js tries to loada.js. A fim de evitar um infiniteloop, uma cópia inacabada do ID

exports object is returned to theb.jsmodule., em seguida termina o carregamento, e seuexportsobjeto é fornecido para oa.jsmódulo.

no momento em que carregou ambos os módulos, ambos estão acabados.A saída deste programa seria assim:

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

planeamento cuidadoso é necessário para permitir que dependências de módulos cíclicos funcionem correctamente dentro de uma aplicação.

file modules#

If the exact filename is not found, then Node.,js tentará carregar o nome do ficheiro com as extensões adicionadas: .js, .json, e finalmente.node.

.js files are interpreted as JavaScript text files, and.json files areparsed as JSON text files. .node files are interpreted as compiled addonmodules loaded with process.dlopen().,

Sem um líder '/' './', ou '../' para indicar um arquivo, o módulo musteither ser um módulo de núcleo ou carregado a partir de uma node_modules pasta.

Se o caminho especificado não existir, require() irá lançar uma Error com o seucode conjunto de propriedades de 'MODULE_NOT_FOUND'.,

Folders as modules#

It is convenient to organize programs and libraries into self-containeddirectories, and then provide a single entry point to those directories.Existem três maneiras em que uma pasta pode ser passada para require() argumento asan.

o primeiro é criar um ficheiro package.json na raiz da pasta,que especifica um main módulo., Um exemplo package.json arquivo mightlook como este:

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

Se isso foi em uma pasta no ./some-library, entãorequire('./some-library') tente carregar./some-library/lib/some-library.js.

Esta é a extensão da consciência de package.json ficheiros dentro do nó.js.

Se não houver package.json de arquivos presentes no diretório, ou se o"main" entrada estiver ausente ou não puder ser resolvido, então o Nó.,jswill attempt to load an index.js orindex.node file out of thatdirectory. Por exemplo, se não houvesse package.json arquivo no previousexample, em seguida, require('./some-library') seria tentar carregar:

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

Se estas tentativas falharem, em seguida, o Nó.,o js irá reportar o módulo inteiro como se perdesse com o erro por omissão:

Error: Cannot find module 'some-library'

a carregar das pastas de modules#

Se não for encontrado lá, então irá para a pasta-mãe, e em breve, até que a raiz do sistema de ficheiros seja atingida.

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

Isso permite que programas para localizar as suas dependências, de modo que eles não notclash.,

é possível exigir arquivos ou sub-módulos específicos distribuídos com o amódulo, incluindo um sufixo de caminho após o nome do módulo. Por exemplorequire('example-module/path/to/file') resolveria path/to/fileem relação ao local onde está localizado. O caminho sufixo segue a mesma semântica de resolução de Módulo.

a carga das pastas globais#

Se a variável de ambiente

é definida como uma lista delimitada por dois pontos de caminhos absolutos, então nó.a js irá procurar nesses caminhos por módulos se não forem encontrados em outro lugar.,

nas janelas, NODE_PATH é delimitada por ponto-e-vírgula () em vez de cólons.

NODE_PATH foi originalmente criado para suportar módulos de carga de caminhos de várzea antes do algoritmo de resolução do módulo atual ser definido.

NODE_PATH ainda é suportado, mas é menos necessário agora que o nó.jsecosystem estabeleceu uma convenção para localizar módulos dependentes.,Às vezes desdobramentos que dependem de NODE_PATH mostram comportamentos surpreendentes quando as pessoas não sabem que NODE_PATH deve ser definido. Às vezes as dependências de amódulo mudam, fazendo com que uma versão diferente (ou mesmo módulo adiferente) seja carregada como o NODE_PATH é pesquisado.

adicionalmente, nó.,js vai procurar na seguinte lista de GLOBAL_FOLDERS:

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

, Onde $HOME é o diretório home do usuário, e $PREFIX é o Nó.jsconfigured node_prefix.

estes são principalmente por razões históricas.

é fortemente encorajado a colocar dependências na pasta local

. Estes serão carregados mais rápido, e mais confiável.,

o invólucro do módulo#

antes do código de um módulo ser executado, nó.o js irá envolvê-lo com um servidor de functionwrapper que se parece com o seguinte:

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

ao fazer isto, Node.js atinge algumas coisas:

• mantém o nível superior de variáveis (definidos com a tag var const ou let) com escopo de módulo de tothe, ao invés de que o objeto global.,
• ajuda global-olhando variáveis que são, na verdade, specificto módulo, tais como:
  • module e exports objetos que a implementação pode usar para exportvalues do módulo.
  • as variáveis de conveniência __filenamee__dirname, contendo o nome absoluto do ficheiro e a localização do directório do módulo.

O escopo do módulo#

__dirname#

• <string>

O nome do diretório do módulo atual. Este é o mesmo que opath.dirname() do __filename.

Exemplo: a execução de node example.js de /Users/mjr

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

__filename#

• <string>

O nome do arquivo do módulo atual. Este é o ficheiro do módulo actual absolutepath com as ligações simbólicas resolvidas.,

para um programa principal isso não é necessariamente o mesmo que o nome do arquivo usado na linha de comando.

ver__dirname para o nome da pasta do 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>

Uma referência para o module.exports que é mais curto para tipo.Veja a secção sobre o atalho de exportação para mais detalhes sobre quando usarexports e quando usar module.exports.

módulo#

• <o módulo>

Uma referência para o módulo atual, consulte a seção sobre omodule 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., Módulos locais e JSON arquivos podem ser importados usinga caminho relativo (por exemplo, ./ ./foo ./bar/baz ../foo) que vai beresolved contra o diretório chamado por __dirname (se definido) orthe diretório de trabalho atual. Os caminhos relativos do estilo POSIX são resolvidos de forma independente do sistema operacional, significando que os exemplos acima funcionarão em janelas da mesma forma que fariam em sistemas Unix.

require.cache#

• <Objeto>

Módulos são armazenados em cache neste objeto, quando são necessários. Ao remover um valor de chave deste objecto, o próximo require irá recarregar o módulo.Isto não se aplica aos addons nativos, para os quais a recarga irá resultar em anerror.

Adicionar ou substituir entradas também é possível. Esta cache é verificada beforenative módulos e se uma correspondência de nome de um módulo nativo é adicionado ao cache,sem exigir chamada isgoing para receber o módulo nativo mais. Use com cuidado!,

require.extensions#

• <Objeto>

Instruir require sobre como lidar com determinadas extensões de ficheiro.

Processo arquivos com a extensão .sjs .js:

require.extensions = require.extensions;

Preterido. No passado, esta lista foi usada para carregar não-Javascriptmódulos no nó.js compilando-os a pedido., No entanto, na prática, existem maneiras muito melhores de fazer isso, tais como carregar módulos através de algum outro nó.jsprogram, ou compilá-los para JavaScript antes do tempo.

evite usar require.extensions. O uso pode causar bugs subtis e resolver asextensões fica mais lento com cada extensão registrada.

require.main#

• <o módulo>

Module objeto que representa a entrada de script carregado quando o Nó.jsprocess lançado.,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., If present, thesepaths are used instead of the default resolution paths, with the exception of GLOBAL_FOLDERS like $HOME/.node_modules, which are alwaysincluded. Cada um destes caminhos é usado como ponto de partida para o algoritmo de resolução de Módulos, o que significa que o id

    hierarquia é checado a partir deste local.,

• Retorna: <string>

Use o interno require() máquinas para procurar a localização de um módulo,mas em vez de carregar o módulo, basta voltar os resolvido nome de arquivo.

Se o módulo não puder ser encontrado, um MODULE_NOT_FOUND Erro é lançado.

require.resolve.paths(request)#

• request <string> O caminho do módulo cuja pesquisa de caminhos estão sendo recuperados.,
• 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#

• <Objeto>

Em cada módulo, o module free variável é uma referência para o objectrepresenting o módulo atual. Por conveniência, module.exports isalso accessible via theexports module-global. module não é realmente global, mas sim local para cada módulo.

módulo.children#

• <module>

os objectos do módulo necessários pela primeira vez por este.

módulo.as exportações#

• <Objeto>

module.exports objeto é criado pelo Module sistema. Às vezes isso não é aceitável; muitos querem que seu módulo seja uma instância de alguma classe. Para isso, atribua o objeto de exportação desejado a module.exports., Atribuir o objeto desejado a exports irá simplesmente refinar a variável local exports, que provavelmente não é o que é desejado.

Por exemplo, suponha que nós estávamos fazendo um módulo chamado a.js:

em Seguida, em um outro arquivo que poderia fazer:

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

Atribuição de module.exports deve ser feito imediatamente. Ele não pode dormir em nenhum callbacks., Isso não funciona:

x.js:

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

y.js:

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

exports atalho#

exports variável está disponível dentro de um módulo de arquivo do escopo, e isassigned o valor de module.exports antes que o módulo é avaliado.,

o module.exports propriedade está a ser completamente substituído por um newobject, é comum também reatribuir exports:

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

Para ilustrar o comportamento, imagine esta hipotética implementação derequire() o que é bastante semelhante ao que é feito realmente por require():

módulo.nome de ficheiro#

• <string>

O totalmente resolvido nome do módulo.

módulo.,id#

• <string>

O identificador do módulo. Tipicamente este é o nome do filme completamente resolvido.

módulo.isPreloading#

• Tipo: <boolean> true se o módulo está em execução durante o Nó.js preloadfase.

módulo.carregado#

• < booleano >

Se o módulo terminou ou não o carregamento, ou se está em processo de carregamento.

módulo.pai#

• <o módulo> | <null> | <indefinido>

O módulo que o primeiro requerido este, ou null se o módulo atual é theentry ponto do processo atual, ou undefined se o módulo foi carregado bysomething que não é um CommonJS módulo (E. G.: REPL ou import).

módulo.path#

• <string>

O nome do diretório do módulo. Isto é geralmente o mesmo que o path.dirname() do module.id.

módulo.caminhos#

• <string>

Os caminhos de pesquisa para o módulo.

módulo.require (id)#

• id <string>
• Retorna: <qualquer> exportados conteúdo do módulo

module.require() método fornece uma maneira para carregar um módulo, como serequire() foi chamado a partir do módulo original.

para fazer isso, é necessário obter uma referência ao objeto module.,Desde require() retorna module.exports, e o module é typicallyonly disponível dentro de um módulo específico do código, ele deve ser explicitamente exportedin para ser usado.

the Module object#

This section was moved toModules: module core module.

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