Node.js v25.0.0 文件

命令與特殊按鍵#

所有 REPL 例項都支援以下特殊命令：

• .break：當正在輸入一個多行表示式時，輸入 .break 命令（或按 Ctrl+C）可以中止該表示式的進一步輸入或處理。
• .clear：將 REPL 的 context 重置為一個空物件，並清除任何正在輸入的多行表示式。
• .exit：關閉 I/O 流，導致 REPL 退出。
• .help：顯示此特殊命令列表。
• .save：將當前的 REPL 會話儲存到一個檔案：> .save ./file/to/save.js
• .load：將一個檔案載入到當前的 REPL 會話中。> .load ./file/to/load.js
• .editor：進入編輯器模式（按 Ctrl+D 完成，按 Ctrl+C 取消）。

> .editor
// Entering editor mode (^D to finish, ^C to cancel)
function welcome(name) {
  return `Hello ${name}!`;
}

welcome('Node.js User');

// ^D
'Hello Node.js User!'
> copy

在 REPL 中，以下組合鍵具有這些特殊效果：

• Ctrl+C：按一次時，效果與 .break 命令相同。在空行上按兩次時，效果與 .exit 命令相同。
• Ctrl+D：效果與 .exit 命令相同。
• Tab：在空行上按時，顯示全域性和區域性（作用域內）的變數。在輸入其他內容時按，顯示相關的自動補全選項。

關於反向 i-search 的鍵繫結，請參見 反向 i-search。所有其他鍵繫結，請參見 TTY 鍵繫結。

預設求值#

預設情況下，所有 repl.REPLServer 例項都使用一個求值函式，該函式可以求值 JavaScript 表示式並提供對 Node.js 內建模組的訪問。在建立 repl.REPLServer 例項時，可以透過傳入一個替代的求值函式來覆蓋此預設行為。

> 1 + 1
2
> const m = 2
undefined
> m + 1
3 copy

import repl from 'node:repl';
const msg = 'message';

repl.start('> ').context.m = msg;const repl = require('node:repl');
const msg = 'message';

repl.start('> ').context.m = msg;copy

$ node repl_test.js
> m
'message' copy

import repl from 'node:repl';
const msg = 'message';

const r = repl.start('> ');
Object.defineProperty(r.context, 'm', {
  configurable: false,
  enumerable: true,
  value: msg,
});const repl = require('node:repl');
const msg = 'message';

const r = repl.start('> ');
Object.defineProperty(r.context, 'm', {
  configurable: false,
  enumerable: true,
  value: msg,
});copy

> fs.createReadStream('./some/file'); copy

> [ 'a', 'b', 'c' ]
[ 'a', 'b', 'c' ]
> _.length
3
> _ += 1
Expression assignment to _ now disabled.
4
> 1 + 1
2
> _
4 copy

> throw new Error('foo');
Uncaught Error: foo
> _error.message
'foo' copy

> await Promise.resolve(123)
123
> await Promise.reject(new Error('REPL await'))
Uncaught Error: REPL await
    at REPL2:1:54
> const timeout = util.promisify(setTimeout);
undefined
> const old = Date.now(); await timeout(1000); console.log(Date.now() - old);
1002
undefined copy

> const m = await Promise.resolve(123)
undefined
> m
123
> m = await Promise.resolve(234)
234
// redeclaring the constant does error
> const m = await Promise.resolve(345)
Uncaught SyntaxError: Identifier 'm' has already been declared copy

反向 i-search#

REPL 支援類似於 ZSH 的雙向反向 i-search。使用 Ctrl+R 向後搜尋，使用 Ctrl+S 向前搜尋。

重複的歷史記錄條目將被跳過。

一旦按下任何與反向搜尋無關的鍵，條目就會被接受。可以透過按 Esc 或 Ctrl+C 來取消。

立即改變方向會從當前位置開始，在預期的方向上搜索下一個條目。

自定義求值函式#

當建立新的 repl.REPLServer 時，可以提供一個自定義的求值函式。這可以用來實現完全定製的 REPL 應用程式。

一個求值函式接受以下四個引數：

• code <string> 將要執行的程式碼（例如 1 + 1）。
• context <Object> 程式碼執行的上下文。這可以是 JavaScript 的 global 上下文，也可以是特定於 REPL 例項的上下文，具體取決於 useGlobal 選項。
• replResourceName <string> 與當前程式碼求值關聯的 REPL 資源的識別符號。這對於除錯目的很有用。
• callback <Function> 在程式碼求值完成後呼叫的函式。該回調函式接受兩個引數：
  • 如果在求值期間發生錯誤，則提供一個錯誤物件，如果沒有錯誤，則為 null/undefined。
  • 程式碼求值的結果（如果提供了錯誤，則此項無關緊要）。

以下示例展示了一個對給定數字進行平方運算的 REPL，如果提供的輸入不是數字，則會列印錯誤：

import repl from 'node:repl';

function byThePowerOfTwo(number) {
  return number * number;
}

function myEval(code, context, replResourceName, callback) {
  if (isNaN(code)) {
    callback(new Error(`${code.trim()} is not a number`));
  } else {
    callback(null, byThePowerOfTwo(code));
  }
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });const repl = require('node:repl');

function byThePowerOfTwo(number) {
  return number * number;
}

function myEval(code, context, replResourceName, callback) {
  if (isNaN(code)) {
    callback(new Error(`${code.trim()} is not a number`));
  } else {
    callback(null, byThePowerOfTwo(code));
  }
}

repl.start({ prompt: 'Enter a number: ', eval: myEval });copy

function myEval(cmd, context, filename, callback) {
  let result;
  try {
    result = vm.runInThisContext(cmd);
  } catch (e) {
    if (isRecoverableError(e)) {
      return callback(new repl.Recoverable(e));
    }
  }
  callback(null, result);
}

function isRecoverableError(error) {
  if (error.name === 'SyntaxError') {
    return /^(Unexpected end of input|Unexpected token)/.test(error.message);
  }
  return false;
} copy

自定義 REPL 輸出#

預設情況下，repl.REPLServer 例項使用 util.inspect() 方法格式化輸出，然後將輸出寫入到提供的 Writable 流（預設為 process.stdout）。showProxy 檢查選項預設設定為 true，colors 選項則根據 REPL 的 useColors 選項設定為 true。

可以在構造時指定 useColors布林值選項，以指示預設寫入器使用 ANSI 樣式程式碼為 util.inspect() 方法的輸出著色。

如果 REPL 作為獨立程式執行，也可以透過使用 inspect.replDefaults 屬性從 REPL 內部更改 REPL 的檢查預設值，該屬性反映了 util.inspect() 的 defaultOptions。

> util.inspect.replDefaults.compact = false;
false
> [1]
[
  1
]
> copy

要完全自定義 repl.REPLServer 例項的輸出，請在構造時為 writer 選項傳入一個新的函式。例如，以下示例簡單地將任何輸入文字轉換為大寫：

import repl from 'node:repl';

const r = repl.start({ prompt: '> ', eval: myEval, writer: myWriter });

function myEval(cmd, context, filename, callback) {
  callback(null, cmd);
}

function myWriter(output) {
  return output.toUpperCase();
}const repl = require('node:repl');

const r = repl.start({ prompt: '> ', eval: myEval, writer: myWriter });

function myEval(cmd, context, filename, callback) {
  callback(null, cmd);
}

function myWriter(output) {
  return output.toUpperCase();
}copy

事件：'exit'#

當 REPL 退出時，會觸發 'exit' 事件。這可能發生在接收到 .exit 命令作為輸入、使用者按兩次 Ctrl+C 傳送 SIGINT 訊號，或者按 Ctrl+D 在輸入流上傳送 'end' 訊號時。監聽器回撥函式在呼叫時不帶任何引數。

replServer.on('exit', () => {
  console.log('Received "exit" event from repl!');
  process.exit();
}); copy

事件：'reset'#

當 REPL 的上下文被重置時，會觸發 'reset' 事件。這發生在接收到 .clear 命令作為輸入時，除非 REPL 使用的是預設求值器，並且 repl.REPLServer 例項建立時 useGlobal 選項被設定為 true。監聽器回撥函式將被呼叫，並以對 context 物件的引用作為唯一引數。

這主要可以用於將 REPL 上下文重新初始化到某個預定義的狀態：

import repl from 'node:repl';

function initializeContext(context) {
  context.m = 'test';
}

const r = repl.start({ prompt: '> ' });
initializeContext(r.context);

r.on('reset', initializeContext);const repl = require('node:repl');

function initializeContext(context) {
  context.m = 'test';
}

const r = repl.start({ prompt: '> ' });
initializeContext(r.context);

r.on('reset', initializeContext);copy

當這段程式碼執行時，全域性變數 'm' 可以被修改，但隨後可以使用 .clear 命令將其重置為初始值：

$ ./node example.js
> m
'test'
> m = 1
1
> m
1
> .clear
Clearing context...
> m
'test'
> copy

replServer.defineCommand(keyword, cmd)#

• keyword <string> 命令關鍵字（不帶前導 . 字元）。
• cmd <Object> | <Function> 命令處理時要呼叫的函式。

replServer.defineCommand() 方法用於向 REPL 例項新增新的以 . 為字首的命令。這類命令透過輸入一個 . 後跟 keyword 來呼叫。cmd 可以是一個 Function 或一個具有以下屬性的 Object：

• help <string> 輸入 .help 時顯示的幫助文字（可選）。
• action <Function> 要執行的函式，可選擇接受一個字串引數。

以下示例展示了向 REPL 例項新增的兩個新命令：

import repl from 'node:repl';

const replServer = repl.start({ prompt: '> ' });
replServer.defineCommand('sayhello', {
  help: 'Say hello',
  action(name) {
    this.clearBufferedCommand();
    console.log(`Hello, ${name}!`);
    this.displayPrompt();
  },
});
replServer.defineCommand('saybye', function saybye() {
  console.log('Goodbye!');
  this.close();
});const repl = require('node:repl');

const replServer = repl.start({ prompt: '> ' });
replServer.defineCommand('sayhello', {
  help: 'Say hello',
  action(name) {
    this.clearBufferedCommand();
    console.log(`Hello, ${name}!`);
    this.displayPrompt();
  },
});
replServer.defineCommand('saybye', function saybye() {
  console.log('Goodbye!');
  this.close();
});copy

然後就可以在 REPL 例項中使用這些新命令了：

> .sayhello Node.js User
Hello, Node.js User!
> .saybye
Goodbye! copy

replServer.displayPrompt([preserveCursor])#

• preserveCursor <boolean>

replServer.displayPrompt() 方法使 REPL 例項準備好接收使用者輸入，將配置的 prompt 列印到 output 的新行，並恢復 input 以接受新輸入。

當輸入多行內容時，會列印一個管道符 '|' 而不是“提示符”。

當 preserveCursor 為 true 時，游標位置將不會重置為 0。

replServer.displayPrompt 方法主要用於在透過 replServer.defineCommand() 方法註冊的命令的 action 函式內部呼叫。

replServer.clearBufferedCommand()#

replServer.clearBufferedCommand() 方法清除任何已緩衝但尚未執行的命令。此方法主要設計用於在透過 replServer.defineCommand() 方法註冊的命令的 action 函式內部呼叫。

replServer.setupHistory(historyConfig, callback)#

• historyConfig <Object> | <string> 歷史檔案的路徑。如果它是一個字串，則為歷史檔案的路徑。如果它是一個物件，它可以有以下屬性：
  • filePath <string> 歷史檔案的路徑
  • size <number> 保留的歷史記錄行數上限。要停用歷史記錄，請將此值設為 0。此選項僅在使用者或內部 output 檢查將 terminal 設定為 true 時才有意義，否則歷史快取機制根本不會初始化。預設值： 30。
  • removeHistoryDuplicates <boolean> 如果為 true，當新增到歷史列表中的新輸入行與舊行重複時，將從列表中移除舊行。預設值： false。
  • onHistoryFileLoaded <Function> 在歷史寫入準備就緒或出錯時呼叫
    • err <Error>
    • repl <repl.REPLServer>
• callback <Function> 在歷史記錄寫入準備就緒或出錯時呼叫（如果在 historyConfig 中提供了 onHistoryFileLoaded，則為可選）
  • err <Error>
  • repl <repl.REPLServer>

為 REPL 例項初始化一個歷史日誌檔案。當執行 Node.js 二進位制檔案並使用命令列 REPL 時，預設會初始化一個歷史檔案。但是，在以程式設計方式建立 REPL 時則不是這種情況。當以程式設計方式使用 REPL 例項時，請使用此方法來初始化歷史日誌檔案。

環境變數選項#

Node.js REPL 的各種行為可以透過以下環境變數進行定製：

• NODE_REPL_HISTORY：當給定一個有效路徑時，持久化的 REPL 歷史記錄將儲存到指定檔案，而不是使用者主目錄下的 .node_repl_history。將此值設定為空字串 '' 將停用持久化的 REPL 歷史記錄。值中的空白字元將被裁剪。在 Windows 平臺上，空值的環境變數是無效的，因此請將此變數設定為一個或多個空格來停用持久化的 REPL 歷史記錄。
• NODE_REPL_HISTORY_SIZE：如果歷史記錄可用，控制將持久化多少行歷史記錄。必須是正數。預設值： 1000。
• NODE_REPL_MODE：可以是 'sloppy' 或 'strict'。預設值： 'sloppy'，這將允許執行非嚴格模式的程式碼。

持久化歷史記錄#

預設情況下，Node.js REPL 會透過將輸入儲存到位於使用者主目錄下的 .node_repl_history 檔案中，來持久化 node REPL 會話之間的歷史記錄。可以透過設定環境變數 NODE_REPL_HISTORY='' 來停用此功能。

將 Node.js REPL 與高階行編輯器一同使用##

對於高階行編輯器，請使用環境變數 NODE_NO_READLINE=1 啟動 Node.js。這將在規範的終端設定中啟動主 REPL 和偵錯程式 REPL，從而允許與 rlwrap 一起使用。

例如，可以將以下內容新增到 .bashrc 檔案中：

alias node="env NODE_NO_READLINE=1 rlwrap node" copy

在同一程序中啟動多個 REPL 例項#

可以針對單個正在執行的 Node.js 例項建立並執行多個 REPL 例項，這些例項共享一個 global 物件（透過將 useGlobal 選項設定為 true），但具有獨立的 I/O 介面。

例如，以下示例在 stdin、一個 Unix 套接字和一個 TCP 套接字上提供了獨立的 REPL，它們都共享同一個 global 物件：

import net from 'node:net';
import repl from 'node:repl';
import process from 'node:process';
import fs from 'node:fs';

let connections = 0;

repl.start({
  prompt: 'Node.js via stdin> ',
  useGlobal: true,
  input: process.stdin,
  output: process.stdout,
});

const unixSocketPath = '/tmp/node-repl-sock';

// If the socket file already exists let's remove it
fs.rmSync(unixSocketPath, { force: true });

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via Unix socket> ',
    useGlobal: true,
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen(unixSocketPath);

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via TCP socket> ',
    useGlobal: true,
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen(5001);const net = require('node:net');
const repl = require('node:repl');
const fs = require('node:fs');

let connections = 0;

repl.start({
  prompt: 'Node.js via stdin> ',
  useGlobal: true,
  input: process.stdin,
  output: process.stdout,
});

const unixSocketPath = '/tmp/node-repl-sock';

// If the socket file already exists let's remove it
fs.rmSync(unixSocketPath, { force: true });

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via Unix socket> ',
    useGlobal: true,
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen(unixSocketPath);

net.createServer((socket) => {
  connections += 1;
  repl.start({
    prompt: 'Node.js via TCP socket> ',
    useGlobal: true,
    input: socket,
    output: socket,
  }).on('exit', () => {
    socket.end();
  });
}).listen(5001);copy

從命令列執行此應用程式將在 stdin 上啟動一個 REPL。其他 REPL 客戶端可以透過 Unix 套接字或 TCP 套接字連線。例如，telnet 對於連線到 TCP 套接字很有用，而 socat 可用於連線到 Unix 和 TCP 套接字。

透過從基於 Unix 套接字的伺服器而不是 stdin 啟動 REPL，可以連線到一個長期執行的 Node.js 程序而無需重啟它。

示例#

// repl-server.js
import repl from 'node:repl';
import net from 'node:net';

net
  .createServer((socket) => {
    const r = repl.start({
      prompt: `socket ${socket.remoteAddress}:${socket.remotePort}> `,
      input: socket,
      output: socket,
      terminal: true,
      useGlobal: false,
    });
    r.on('exit', () => {
      socket.end();
    });
    r.context.socket = socket;
  })
  .listen(1337);// repl-server.js
const repl = require('node:repl');
const net = require('node:net');

net
  .createServer((socket) => {
    const r = repl.start({
      prompt: `socket ${socket.remoteAddress}:${socket.remotePort}> `,
      input: socket,
      output: socket,
      terminal: true,
      useGlobal: false,
    });
    r.on('exit', () => {
      socket.end();
    });
    r.context.socket = socket;
  })
  .listen(1337);copy

// repl-client.js
import net from 'node:net';
import process from 'node:process';

const sock = net.connect(1337);

process.stdin.pipe(sock);
sock.pipe(process.stdout);

sock.on('connect', () => {
  process.stdin.resume();
  process.stdin.setRawMode(true);
});

sock.on('close', () => {
  process.stdin.setRawMode(false);
  process.stdin.pause();
  sock.removeListener('close', done);
});

process.stdin.on('end', () => {
  sock.destroy();
  console.log();
});

process.stdin.on('data', (b) => {
  if (b.length === 1 && b[0] === 4) {
    process.stdin.emit('end');
  }
});// repl-client.js
const net = require('node:net');

const sock = net.connect(1337);

process.stdin.pipe(sock);
sock.pipe(process.stdout);

sock.on('connect', () => {
  process.stdin.resume();
  process.stdin.setRawMode(true);
});

sock.on('close', () => {
  process.stdin.setRawMode(false);
  process.stdin.pause();
  sock.removeListener('close', done);
});

process.stdin.on('end', () => {
  sock.destroy();
  console.log();
});

process.stdin.on('data', (b) => {
  if (b.length === 1 && b[0] === 4) {
    process.stdin.emit('end');
  }
});copy

import http from 'node:http';
import repl from 'node:repl';

const server = http.createServer((req, res) => {
  res.setHeader('content-type', 'multipart/octet-stream');

  repl.start({
    prompt: 'curl repl> ',
    input: req,
    output: res,
    terminal: false,
    useColors: true,
    useGlobal: false,
  });
});

server.listen(8000);const http = require('node:http');
const repl = require('node:repl');

const server = http.createServer((req, res) => {
  res.setHeader('content-type', 'multipart/octet-stream');

  repl.start({
    prompt: 'curl repl> ',
    input: req,
    output: res,
    terminal: false,
    useColors: true,
    useGlobal: false,
  });
});

server.listen(8000);copy