Node.js v26.0.0 說明文件

Net#

node:net 模組提供了一個非同步網路 API，用於建立基於串流的 TCP 或 IPC 伺服器 (net.createServer()) 與客戶端 (net.createConnection())。

可以透過以下方式存取：

import net from 'node:net';
const net = require('node:net');
copy

IPC 支援#

node:net 模組在 Windows 上支援使用具名管道 (named pipes) 進行 IPC，在其他作業系統上則支援使用 Unix 域通訊端 (Unix domain sockets)。

識別 IPC 連線的路徑#

net.connect()、net.createConnection()、server.listen() 與 socket.connect() 接受 path 參數來識別 IPC 端點。

在 Unix 上，本地網域也被稱為 Unix 域。路徑是一個檔案系統路徑名稱。當路徑名稱長度大於 sizeof(sockaddr_un.sun_path) 的長度時，會拋出錯誤。典型值在 Linux 上為 107 位元組，在 macOS 上為 103 位元組。如果 Node.js API 抽象層建立了 Unix 域通訊端，它也會同時解除該通訊端的連結 (unlink)。例如，net.createServer() 可能會建立一個 Unix 域通訊端，而 server.close() 會解除其連結。但如果使用者是在這些抽象層之外建立 Unix 域通訊端，則使用者需要自行移除它。當 Node.js API 建立了 Unix 域通訊端但程式隨後當機時也是如此。簡而言之，Unix 域通訊端會顯示在檔案系統中，並持續存在直到被解除連結。在 Linux 上，您可以透過在路徑開頭添加 \0 來使用 Unix 抽象通訊端 (abstract socket)，例如 \0abstract。Unix 抽象通訊端的路徑在檔案系統中不可見，當所有對該通訊端的開啟參考都關閉時，它會自動消失。

在 Windows 上，本地網域是使用具名管道實作的。路徑必須引用 \\?\pipe\ 或 \\.\pipe\ 中的項目。允許使用任何字元，但後者可能會對管道名稱進行一些處理，例如解析 .. 序列。儘管看起來可能不同，但管道命名空間是扁平的。管道不會持久存在。當最後一個對它們的參考關閉時，它們就會被移除。與 Unix 域通訊端不同，Windows 會在擁有該管道的行程結束時關閉並移除管道。

JavaScript 字串逸出 (escaping) 要求路徑需指定額外的反斜線逸出，例如：

net.createServer().listen(
  path.join('\\\\?\\pipe', process.cwd(), 'myctl'));
copy

類別：net.BlockList#

BlockList 物件可用於某些網路 API，以指定停用特定 IP 位址、IP 範圍或 IP 子網路的連入或連出存取規則。

blockList.addAddress(address[, type])#

• address <string> | <net.SocketAddress> 一個 IPv4 或 IPv6 位址。
• type <string> 'ipv4' 或 'ipv6' 之一。預設值： 'ipv4'。

新增一條規則來封鎖指定的 IP 位址。

blockList.addRange(start, end[, type])#

• start <string> | <net.SocketAddress> 範圍中的起始 IPv4 或 IPv6 位址。
• end <string> | <net.SocketAddress> 範圍中的結束 IPv4 或 IPv6 位址。
• type <string> 'ipv4' 或 'ipv6' 之一。預設值： 'ipv4'。

新增一條規則來封鎖從 start (包含) 到 end (包含) 的 IP 位址範圍。

blockList.addSubnet(net, prefix[, type])#

• net <string> | <net.SocketAddress> 網路 IPv4 或 IPv6 位址。
• prefix <number> CIDR 前綴位元數。對於 IPv4，此值必須介於 0 到 32 之間。對於 IPv6，此值必須介於 0 到 128 之間。
• type <string> 'ipv4' 或 'ipv6' 之一。預設值： 'ipv4'。

新增一條規則來封鎖指定為子網路遮罩的 IP 位址範圍。

blockList.check(address[, type])#

• address <string> | <net.SocketAddress> 要檢查的 IP 位址。
• type <string> 'ipv4' 或 'ipv6' 之一。預設值： 'ipv4'。
• 傳回：<boolean>

如果指定的 IP 位址符合 BlockList 中新增的任何規則，則返回 true。

const blockList = new net.BlockList();
blockList.addAddress('123.123.123.123');
blockList.addRange('10.0.0.1', '10.0.0.10');
blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6');

console.log(blockList.check('123.123.123.123'));  // Prints: true
console.log(blockList.check('10.0.0.3'));  // Prints: true
console.log(blockList.check('222.111.111.222'));  // Prints: false

// IPv6 notation for IPv4 addresses works:
console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true
console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true
copy

blockList.rules#

• 類型：<string[]>

新增到封鎖清單中的規則列表。

BlockList.isBlockList(value)#

• value <any> 任何 JS 值。
• 如果 value 是 net.BlockList，則返回 true。

blockList.fromJSON(value)#

const blockList = new net.BlockList();
const data = [
  'Subnet: IPv4 192.168.1.0/24',
  'Address: IPv4 10.0.0.5',
  'Range: IPv4 192.168.2.1-192.168.2.10',
  'Range: IPv4 10.0.0.1-10.0.0.10',
];
blockList.fromJSON(data);
blockList.fromJSON(JSON.stringify(data));
copy

• value Blocklist.rules

blockList.toJSON()#

• 返回 Blocklist.rules

類別：net.SocketAddress#

new net.SocketAddress([options])#

• options <Object>
  • address <string> 作為 IPv4 或 IPv6 字串的網路位址。預設值：如果 family 為 'ipv4' 則為 '127.0.0.1'；如果 family 為 'ipv6' 則為 '::'。
  • family <string> 'ipv4' 或 'ipv6' 之一。預設值：'ipv4'。
  • flowlabel <number> 僅在 family 為 'ipv6' 時使用的 IPv6 流量標籤。
  • port <number> 一個 IP 連接埠。

socketaddress.address#

• 類型：<string>

socketaddress.family#

• 型別：<string> 'ipv4' 或 'ipv6'。

socketaddress.flowlabel#

• 類型：<number>

socketaddress.port#

• 類型：<number>

SocketAddress.parse(input)#

• input <string> 包含 IP 位址和選用連接埠的輸入字串，例如 123.1.2.3:1234 或 [1::1]:1234。
• 返回：<net.SocketAddress> 如果解析成功則返回 SocketAddress。否則返回 undefined。

類別：net.Server#

• 繼承自：<EventEmitter>

此類別用於建立 TCP 或 IPC 伺服器。

new net.Server([options][, connectionListener])#

• options <Object> 請參閱 net.createServer([options][, connectionListener])。
• connectionListener <Function> 自動設定為 'connection' 事件的接聽程式。
• 返回：<net.Server>

net.Server 是一個具有下列事件的 EventEmitter

事件：'close'#

當伺服器關閉時觸發。如果仍有連線存在，則直到所有連線結束後才會觸發此事件。

事件：'connection'#

• 型別：<net.Socket> 連線物件

當建立新連線時觸發。socket 是 net.Socket 的實例。

事件：'error'#

• 類型：<Error>

當發生錯誤時觸發。與 net.Socket 不同，除非手動呼叫 server.close()，否則在此事件之後不會直接觸發 'close' 事件。請參閱 server.listen() 討論中的範例。

事件：'listening'#

在呼叫 server.listen() 並完成伺服器綁定後觸發。

事件：'drop'#

當連線數量達到 server.maxConnections 的閾值時，伺服器將捨棄新連線並改為觸發 'drop' 事件。如果是 TCP 伺服器，參數如下，否則參數為 undefined。

• data <Object> 傳遞給事件接聽程式的參數。
  • localAddress <string> 本地位址。
  • localPort <number> 本地連接埠。
  • localFamily <string> 本地位址家族。
  • remoteAddress <string> 遠端位址。
  • remotePort <number> 遠端連接埠。
  • remoteFamily <string> 遠端 IP 家族。'IPv4' 或 'IPv6'。

server.address()#

• 返回：<Object> | <string> | <null>

如果接聽的是 IP 通訊端，則返回作業系統回報的已綁定 address、位址 family 名稱以及伺服器 port (用於在取得 OS 分配的位址時找出分配到哪個連接埠)：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

對於接聽管道或 Unix 域通訊端的伺服器，名稱會以字串形式返回。

const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});
copy

在 'listening' 事件觸發前，或在呼叫 server.close() 後，server.address() 會返回 null。

server.close([callback])#

• callback <Function> 當伺服器關閉時呼叫。
• 返回：<net.Server>

停止伺服器接受新連線並保留現有連線。此函式是非同步的，當所有連線結束且伺服器觸發 'close' 事件時，伺服器才會最終關閉。一旦 'close' 事件發生，選用的 callback 就會被呼叫。與該事件不同的是，如果在關閉時伺服器並未開啟，則呼叫 callback 時會將 Error 作為其唯一參數。

server[Symbol.asyncDispose]()#

呼叫 server.close() 並傳回一個在伺服器關閉時實現（fulfill）的 Promise。

server.getConnections(callback)#

• callback <Function>
• 返回：<net.Server>

非同步獲取伺服器上的並行連線數。當通訊端被發送到分叉行程 (forks) 時也能運作。

回呼函式應接受兩個參數：err 和 count。

server.listen()#

開始接聽連線。net.Server 可以是 TCP 伺服器或 IPC 伺服器，具體取決於其接聽的對象。

可能的簽署方式：

• server.listen(handle[, backlog][, callback])
• server.listen(options[, callback])
• 用於 IPC 伺服器的 server.listen(path[, backlog][, callback])
• 用於 TCP 伺服器的 server.listen([port[, host[, backlog]]][, callback])

此函式是非同步的。當伺服器開始接聽時，會觸發 'listening' 事件。最後一個參數 callback 將被新增為 'listening' 事件的接聽程式。

所有的 listen() 方法都可以接受 backlog 參數來指定待處理連線隊列的最大長度。實際長度將由作業系統透過 sysctl 設定 (如 Linux 上的 tcp_max_syn_backlog 和 somaxconn) 決定。此參數的預設值為 511 (不是 512)。

所有的 net.Socket 都會設定為 SO_REUSEADDR (詳細資訊請參閱 socket(7))。

當且僅當第一次 server.listen() 呼叫期間發生錯誤，或已呼叫 server.close() 時，才能再次呼叫 server.listen() 方法。否則將拋出 ERR_SERVER_ALREADY_LISTEN 錯誤。

接聽時最常遇到的錯誤之一是 EADDRINUSE。當另一個伺服器已在接聽要求的 port/path/handle 時就會發生這種情況。處理此問題的一種方法是在一段時間後重試：

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});
copy

server.listen(handle[, backlog][, callback])#

• handle <Object>
• backlog <number> server.listen() 函式的通用參數
• callback <Function>
• 返回：<net.Server>

在已綁定到連接埠、Unix 域通訊端或 Windows 具名管道的指定 handle 上開始接聽連線。

handle 物件可以是一個伺服器、一個通訊端 (任何具有底層 _handle 成員的物件)，或者是一個具有有效檔案描述符 fd 成員的物件。

Windows 不支援接聽檔案描述符。

server.listen(options[, callback])#

• options <Object> 必填。支援下列屬性：
  • backlog <number> server.listen() 函式的通用參數。
  • exclusive <boolean> 預設值： false
  • host <string>
  • ipv6Only <boolean> 對於 TCP 伺服器，將 ipv6Only 設定為 true 將停用雙堆疊 (dual-stack) 支援，意即綁定到主機 :: 不會同時綁定 0.0.0.0。預設值： false。
  • reusePort <boolean> 對於 TCP 伺服器，將 reusePort 設定為 true 允許同一個主機上的多個通訊端綁定到同一個連接埠。傳入的連線由作業系統分配給接聽中的通訊端。此選項僅在某些平台上可用，例如 Linux 3.9+、DragonFlyBSD 3.6+、FreeBSD 12.0+、Solaris 11.4 和 AIX 7.2.5+。在不支援的平台上，此選項會引發錯誤。預設值： false。
  • path <string> 如果指定了 port 則會被忽略。請參閱識別 IPC 連線的路徑。
  • port <number>
  • readableAll <boolean> 對於 IPC 伺服器，使管道對所有使用者皆可讀取。預設值： false。
  • signal <AbortSignal> 可用於關閉接聽伺服器的 AbortSignal。
  • writableAll <boolean> 對於 IPC 伺服器，使管道對所有使用者皆可寫入。預設值： false。
• callback <Function> 函式。
• 返回：<net.Server>

如果指定了 port，其行為與 server.listen([port[, host[, backlog]]][, callback]) 相同。否則，如果指定了 path，其行為與 server.listen(path[, backlog][, callback]) 相同。如果兩者都未指定，則會拋出錯誤。

如果 exclusive 為 false (預設值)，則叢集工作行程 (cluster workers) 將使用同一個底層控制代碼 (handle)，從而共用連線處理職責。當 exclusive 為 true 時，控制代碼不共用，嘗試共用連接埠會導致錯誤。下方顯示了一個接聽獨佔連接埠的範例。

server.listen({
  host: 'localhost',
  port: 80,
  exclusive: true,
});
copy

當 exclusive 為 true 且底層控制代碼共用時，可能會有數個工作行程使用不同的 backlog 查詢同一個控制代碼。在這種情況下，將使用傳遞給主行程的第一個 backlog。

以 root 身分啟動 IPC 伺服器可能會導致無權限的使用者無法存取伺服器路徑。使用 readableAll 和 writableAll 可以讓所有使用者都能存取伺服器。

如果啟用了 signal 選項，在對應的 AbortController 上呼叫 .abort() 相當於在伺服器上呼叫 .close()

const controller = new AbortController();
server.listen({
  host: 'localhost',
  port: 80,
  signal: controller.signal,
});
// Later, when you want to close the server.
controller.abort();
copy

server.listen(path[, backlog][, callback])#

• path <string> 伺服器應接聽的路徑。請參閱識別 IPC 連線的路徑。
• backlog <number> server.listen() 函式的通用參數。
• callback <Function>。
• 返回：<net.Server>

開始接聽指定 path 上的 IPC 伺服器連線。

server.listen([port[, host[, backlog]]][, callback])#

• port <number>
• host <string>
• backlog <number> server.listen() 函式的通用參數。
• callback <Function>。
• 返回：<net.Server>

開始接聽指定 port 和 host 上的 TCP 伺服器連線。

如果省略 port 或其值為 0，作業系統將分配一個隨意的未使用連接埠，可以在 'listening' 事件觸發後透過 server.address().port 檢索該連接埠。

如果省略 host，當 IPv6 可用時，伺服器將接受 未指定 IPv6 位址 (::) 上的連線，否則接受 未指定 IPv4 位址 (0.0.0.0) 上的連線。

在大多數作業系統中，接聽 未指定 IPv6 位址 (::) 可能會導致 net.Server 同時接聽 未指定 IPv4 位址 (0.0.0.0)。

server.listening#

• 類型: <boolean> 指示伺服器是否正在監聽連線。

server.maxConnections#

• 類型：<integer>

當連線數量達到 server.maxConnections 閾值時：

1. 如果行程未在叢集 (cluster) 模式下執行，Node.js 將關閉連線。

2. 如果行程在叢集模式下執行，Node.js 預設會將連線路由到另一個工作行程。若要改為關閉連線，請將 server.dropMaxConnection 設定為 true。

不建議在透過 child_process.fork() 將通訊端發送給子行程後使用此選項。

server.dropMaxConnection#

• 類型：<boolean>

將此屬性設定為 true，可以在連線數量達到 server.maxConnections 閾值時開始關閉連線。此設定僅在叢集模式下有效。

server.ref()#

• 返回：<net.Server>

與 unref() 相反，如果一個伺服器是最後剩下的伺服器 (預設行為)，在先前已 unref 的伺服器上呼叫 ref() 將不會讓程式退出。如果伺服器已經 ref，再次呼叫 ref() 將沒有效果。

server.unref()#

• 返回：<net.Server>

在伺服器上呼叫 unref()，如果這是事件系統中唯一活躍的伺服器，將允許程式退出。如果伺服器已經 unref，再次呼叫 unref() 將沒有效果。

類別：net.Socket#

• 繼承自：<stream.Duplex>

此類別是 TCP 通訊端或串流 IPC 端點的抽象化 (在 Windows 上使用具名管道，在其他平台上使用 Unix 域通訊端)。它也是一個 EventEmitter。

使用者可以建立 net.Socket 並直接用於與伺服器互動。例如，它由 net.createConnection() 返回，因此使用者可以使用它與伺服器通訊。

它也可以由 Node.js 建立，並在接收到連線時傳遞給使用者。例如，它會傳遞給 net.Server 上觸發的 'connection' 事件的接聽程式，因此使用者可以使用它與用戶端互動。

new net.Socket([options])#

• options <Object> 可用選項如下：
  • allowHalfOpen <boolean> 如果設定為 false，則當可讀端結束時，通訊端會自動結束可寫端。詳細資訊請參閱 net.createServer() 和 'end' 事件。預設值： false。
  • blockList <net.BlockList> blockList 可用於停用特定 IP 位址、IP 範圍或 IP 子網路的連出存取。
  • fd <number> 如果指定，則使用指定的檔案描述符封裝現有的通訊端，否則將建立一個新的通訊端。
  • keepAlive <boolean> 如果設定為 true，則在建立連線後立即在通訊端上啟用 keep-alive 功能，類似於 socket.setKeepAlive() 中的操作。預設值： false。
  • keepAliveInitialDelay <number> 如果設為正數，它會設定在閒置 socket 上發送第一個 keepalive 探測之前的初始延遲。預設值： 0。
  • noDelay <boolean> 如果設定為 true，則在建立通訊端後立即停用 Nagle 演算法。預設值： false。
  • onread <Object> 如果指定，傳入的資料將儲存在單一 buffer 中，並在資料到達通訊端時傳遞給提供的 callback。這將導致串流功能不提供任何資料。通訊端仍會照常觸發 'error'、'end' 和 'close' 等事件。pause() 和 resume() 等方法也會按預期運作。
    • buffer <Buffer> | <Uint8Array> | <Function> 用於儲存傳入資料的可重用記憶體區塊，或是返回此類區塊的函式。
    • callback <Function> 針對每個傳入資料塊呼叫此函式。傳遞給它的兩個參數是：寫入 buffer 的位元組數以及對 buffer 的參考。從此函式返回 false 以隱式地 pause() 通訊端。此函式將在全域上下文中執行。
  • readable <boolean> 當傳遞了 fd 時允許讀取通訊端，否則忽略。預設值： false。
  • signal <AbortSignal> 可用於銷毀通訊端的 Abort 訊號。
  • typeOfService <number> 初始服務類型 (TOS) 值。
  • writable <boolean> 當傳遞了 fd 時允許寫入通訊端，否則忽略。預設值： false。
• 返回：<net.Socket>

建立一個新的通訊端物件。

新建立的通訊端可以是 TCP 通訊端或串流 IPC 端點，具體取決於其 connect() 的對象。

事件：'close'#

• hadError <boolean> 如果通訊端發生傳輸錯誤則為 true。

通訊端完全關閉後觸發。參數 hadError 是一個布林值，表示通訊端是否因傳輸錯誤而關閉。

事件：'connect'#

通訊端連線成功建立時觸發。請參閱 net.createConnection()。

事件：'connectionAttempt'#

• ip <string> 通訊端嘗試連接的 IP。
• port <number> 通訊端嘗試連接的連接埠。
• family <number> IP 家族。IPv6 為 6，IPv4 為 4。

當啟動新的連線嘗試時觸發。如果在 socket.connect(options) 中啟用了家族自動選擇演算法，此事件可能會被觸發多次。

事件：'connectionAttemptFailed'#

• ip <string> 通訊端嘗試連接的 IP。
• port <number> 通訊端嘗試連接的連接埠。
• family <number> IP 家族。IPv6 為 6，IPv4 為 4。
• error <Error> 與失敗相關的錯誤。

當連線嘗試失敗時觸發。如果在 socket.connect(options) 中啟用了家族自動選擇演算法，此事件可能會被觸發多次。

事件：'connectionAttemptTimeout'#

• ip <string> 通訊端嘗試連接的 IP。
• port <number> 通訊端嘗試連接的連接埠。
• family <number> IP 家族。IPv6 為 6，IPv4 為 4。

當連線嘗試逾時時觸發。僅當在 socket.connect(options) 中啟用了家族自動選擇演算法時才會觸發 (且可能觸發多次)。

事件：'data'#

• 型別：<Buffer> | <string>

接收到資料時觸發。參數 data 將是一個 Buffer 或 String。資料編碼由 socket.setEncoding() 設定。

如果 Socket 觸發 'data' 事件時沒有接聽程式，則資料將會遺失。

事件：'drain'#

當寫入緩衝區變空時觸發。可用於調節上傳流量。

另請參閱：socket.write() 的返回值。

事件：'end'#

當通訊端的另一端發送傳輸結束訊號時觸發，從而結束通訊端的可讀端。

預設情況下 (allowHalfOpen 為 false)，通訊端將發回傳輸結束封包，並在寫完擱置的寫入隊列後銷毀其檔案描述符。但是，如果 allowHalfOpen 設定為 true，通訊端將不會自動 end() 其可寫端，允許使用者寫入任意數量的資料。使用者必須明確呼叫 end() 來關閉連線 (即發回 FIN 封包)。

事件：'error'#

• 類型：<Error>

發生錯誤時觸發。'close' 事件將在此事件之後直接被呼叫。

事件：'lookup'#

在解析主機名稱之後但在連接之前觸發。不適用於 Unix 通訊端。

• err <Error> | <null> 錯誤物件。請參閱 dns.lookup()。
• address <string> IP 位址。
• family <number> | <null> 位址類型。請參閱 dns.lookup()。
• host <string> 主機名稱。

事件：'ready'#

當通訊端準備好使用時觸發。

在 'connect' 之後立即觸發。

事件：'timeout'#

如果通訊端因閒置而逾時則觸發。這僅是通知通訊端已閒置。使用者必須手動關閉連線。

另請參閱：socket.setTimeout()。

socket.address()#

• 傳回：<Object>

返回作業系統回報的通訊端已綁定位址 address、位址 family 名稱和連接埠 port：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses#

• 類型：<string[]>

此屬性僅在 socket.connect(options) 中啟用了家族自動選擇演算法時存在，它是一個已嘗試過的位址陣列。

每個位址都是 $IP:$PORT 格式的字串。如果連線成功，則最後一個位址是通訊端目前連接的位址。

socket.bufferSize#

• 類型：<integer>

此屬性顯示為寫入而緩衝的字元數。緩衝區可能包含編碼後長度尚不明確的字串。因此，此數字僅是緩衝區中位元組數的近似值。

net.Socket 具有 socket.write() 始終有效的特性。這是為了幫助使用者快速上手。電腦並不總是能跟上寫入通訊端的資料量。網路連線可能太慢。Node.js 會在內部排隊寫入通訊端的資料，並在可能的情況下透過線路將其發送出去。

這種內部緩衝的後果是記憶體可能會增長。遇到 bufferSize 過大或持續增長的使用者，應嘗試使用 socket.pause() 和 socket.resume() 來「調節」程式中的資料流。

socket.bytesRead#

• 類型：<integer>

接收到的位元組量。

socket.bytesWritten#

• 類型：<integer>

發送的位元組量。

socket.connect()#

在指定的通訊端上啟動連線。

可能的簽署方式：

• socket.connect(options[, connectListener])
• 用於 IPC 連線的 socket.connect(path[, connectListener])。
• 用於 TCP 連線的 socket.connect(port[, host][, connectListener])。
• 返回：<net.Socket> 通訊端本身。

此函式是非同步的。建立連線時，將觸發 'connect' 事件。如果連接出現問題，將觸發 'error' 事件，並將錯誤傳遞給 'error' 接聽程式，而不是觸發 'connect' 事件。最後一個參數 connectListener (如果提供) 將被新增為 'connect' 事件的一次性接聽程式。

此函式僅應用於在觸發 'close' 後重新連接通訊端，否則可能導致未定義的行為。

socket.connect(options[, connectListener])#

• options <Object>
• connectListener <Function> socket.connect() 方法的通用參數。將被新增為 'connect' 事件的一次性接聽程式。
• 返回：<net.Socket> 通訊端本身。

在指定的通訊端上啟動連線。通常不需要此方法，通訊端應使用 net.createConnection() 建立並開啟。僅在實作自訂 Socket 時才使用此方法。

對於 TCP 連線，可用的 options 有：

• autoSelectFamily <boolean>：如果設定為 true，則啟用一個家族自動偵測演算法，該演算法鬆散地實作了 RFC 8305 的第 5 節。傳遞給查詢的 all 選項設定為 true，且通訊端會按順序嘗試連接所有取得的 IPv6 和 IPv4 位址，直到建立連線。首先嘗試第一個返回的 AAAA 位址，然後是第一個返回的 A 位址，接著是第二個返回的 AAAA 位址，依此類推。每次連線嘗試 (除了最後一次) 都會給予 autoSelectFamilyAttemptTimeout 選項指定的時間量，逾時後則嘗試下一個位址。如果 family 選項不是 0 或設定了 localAddress，則會忽略此選項。如果至少有一個連線成功，則不會觸發連線錯誤。如果所有連線嘗試都失敗，則會觸發一個包含所有失敗嘗試的 AggregateError。預設值： net.getDefaultAutoSelectFamily()。
• autoSelectFamilyAttemptTimeout <number>：使用 autoSelectFamily 選項時，在嘗試下一個位址之前等待連線嘗試完成的時間量 (以毫秒為單位)。如果設定為小於 10 的正整數，則將改用值 10。預設值： net.getDefaultAutoSelectFamilyAttemptTimeout()。
• family <number>：IP 堆疊版本。必須是 4、6 或 0。值 0 表示允許 IPv4 和 IPv6 位址。預設值： 0。
• hints <number> 選填的 dns.lookup() 提示。
• host <string> 通訊端應連接的主機。預設值： 'localhost'。
• localAddress <string> 通訊端應從中連接的本地位址。
• localPort <number> 通訊端應從中連接的本地連接埠。
• lookup <Function> 自定義查找函數。預設值： dns.lookup()。
• port <number> 必填。通訊端應連接的連接埠。

對於 IPC 連線，可用的 options 有：

• path <string> 必填。用戶端應連接的路徑。請參閱識別 IPC 連線的路徑。如果提供了此參數，則會忽略上述 TCP 特定選項。

socket.connect(path[, connectListener])#

• path <string> 用戶端應連接的路徑。請參閱識別 IPC 連線的路徑。
• connectListener <Function> socket.connect() 方法的通用參數。將被新增為 'connect' 事件的一次性接聽程式。
• 返回：<net.Socket> 通訊端本身。

在指定的通訊端上啟動 IPC 連線。

呼叫 socket.connect(options[, connectListener]) 的別名，其中 options 為 { path: path }。

socket.connect(port[, host][, connectListener])#

• port <number> 用戶端應連接的連接埠。
• host <string> 用戶端應連接的主機。
• connectListener <Function> socket.connect() 方法的通用參數。將被新增為 'connect' 事件的一次性接聽程式。
• 返回：<net.Socket> 通訊端本身。

在指定的通訊端上啟動 TCP 連線。

呼叫 socket.connect(options[, connectListener]) 的別名，其中 options 為 {port: port, host: host}。

socket.connecting#

• 類型：<boolean>

如果為 true，則表示已呼叫 socket.connect(options[, connectListener]) 且尚未完成。它會維持 true 直到通訊端連接成功，然後設定為 false 並觸發 'connect' 事件。請注意，socket.connect(options[, connectListener]) 的回呼函式是 'connect' 事件的接聽程式。

socket.destroy([error])#

• error <Object>
• 返回：<net.Socket>

確保此通訊端上不再發生 I/O 活動。銷毀串流並關閉連線。

詳見 writable.destroy()。

socket.destroyed#

• 型別：<boolean> 指示連線是否已銷毀。一旦連線被銷毀，就無法再使用它傳輸資料。

詳見 writable.destroyed。

socket.destroySoon()#

在所有資料寫入後銷毀通訊端。如果 'finish' 事件已經觸發，則通訊端會立即銷毀。如果通訊端仍然可寫，它會隱式呼叫 socket.end()。

socket.end([data[, encoding]][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 僅在資料為 string 時使用。預設值： 'utf8'。
• callback <Function> 當通訊端結束時的選用回呼。
• 返回：<net.Socket> 通訊端本身。

半關閉 (Half-closes) 通訊端。即發送一個 FIN 封包。伺服器可能仍會發送一些資料。

詳細資訊請參閱 writable.end()。

socket.localAddress#

• 類型：<string>

遠端用戶端連接的本地 IP 位址的字串表示。例如，在一台接聽 '0.0.0.0' 的伺服器上，如果用戶端連接到 '192.168.1.1'，則 socket.localAddress 的值將為 '192.168.1.1'。

socket.localPort#

• 類型：<integer>

本地連接埠的數字表示。例如，80 或 21。

socket.localFamily#

• 類型：<string>

本地 IP 家族的字串表示。'IPv4' 或 'IPv6'。

socket.pause()#

• 返回：<net.Socket> 通訊端本身。

暫停讀取資料。即不會觸發 'data' 事件。可用於調節上傳流量。

socket.pending#

• 類型：<boolean>

如果通訊端尚未連接，則為 true，原因可能是尚未呼叫 .connect()，或者仍在連接過程中 (請參閱 socket.connecting)。

socket.ref()#

• 返回：<net.Socket> 通訊端本身。

與 unref() 相反，如果一個通訊端是最後剩下的通訊端 (預設行為)，在先前已 unref 的通訊端上呼叫 ref() 將不會讓程式退出。如果通訊端已經 ref，再次呼叫 ref 將沒有效果。

socket.remoteAddress#

• 類型：<string>

遠端 IP 位址的字串表示。例如，'74.125.127.100' 或 '2001:4860:a005::68'。如果通訊端已銷毀 (例如用戶端已斷開連接)，值可能為 undefined。

socket.remoteFamily#

• 類型：<string>

遠端 IP 家族的字串表示。'IPv4' 或 'IPv6'。如果通訊端已銷毀 (例如用戶端已斷開連接)，值可能為 undefined。

socket.remotePort#

• 類型：<integer>

遠端連接埠的數字表示。例如，80 或 21。如果通訊端已銷毀 (例如用戶端已斷開連接)，值可能為 undefined。

socket.resetAndDestroy()#

• 返回：<net.Socket>

透過發送 RST 封包關閉 TCP 連線並銷毀串流。如果此 TCP 通訊端處於連接狀態，它將發送一個 RST 封包並在連接後銷毀此 TCP 通訊端。否則，它將使用 ERR_SOCKET_CLOSED 錯誤呼叫 socket.destroy。如果這不是 TCP 通訊端 (例如管道)，呼叫此方法將立即拋出 ERR_INVALID_HANDLE_TYPE 錯誤。

socket.resume()#

• 返回：<net.Socket> 通訊端本身。

呼叫 socket.pause() 後恢復讀取。

socket.setEncoding([encoding])#

• encoding <string>
• 返回：<net.Socket> 通訊端本身。

將通訊端設定為 可讀串流 (Readable Stream) 的編碼。詳細資訊請參閱 readable.setEncoding()。

socket.setKeepAlive([enable][, initialDelay])#

• enable <boolean> 預設值： false
• initialDelay <number> 預設值： 0
• 返回：<net.Socket> 通訊端本身。

啟用/停用 keep-alive 功能，並可選地設定在閒置通訊端上發送第一個 keepalive 探測之前的初始延遲。

設定 initialDelay (以毫秒為單位) 來設定最後一個接收到的資料封包與第一個 keepalive 探測之間的延遲。將 initialDelay 設定為 0 將保持預設 (或先前) 設定的值不變。

啟用 keep-alive 功能將設定下列通訊端選項：

• SO_KEEPALIVE=1
• TCP_KEEPIDLE=initialDelay
• TCP_KEEPCNT=10
• TCP_KEEPINTVL=1

socket.setNoDelay([noDelay])#

• noDelay <boolean> 預設值： true
• 返回：<net.Socket> 通訊端本身。

啟用/停用 Nagle 演算法的使用。

建立 TCP 連線時，會預設啟用 Nagle 演算法。

Nagle 演算法在資料透過網路發送之前會對其進行延遲。它嘗試以犧牲延遲為代價來優化吞吐量。

對 noDelay 傳遞 true 或不傳遞參數將停用通訊端的 Nagle 演算法。對 noDelay 傳遞 false 將啟用 Nagle 演算法。

socket.setTimeout(timeout[, callback])#

• timeout <number>
• callback <Function>
• 返回：<net.Socket> 通訊端本身。

設定通訊端在閒置 timeout 毫秒後逾時。預設情況下 net.Socket 沒有逾時時間。

當觸發閒置逾時時，通訊端將接收到一個 'timeout' 事件，但連線不會被切斷。使用者必須手動呼叫 socket.end() 或 socket.destroy() 來結束連線。

socket.setTimeout(3000);
socket.on('timeout', () => {
  console.log('socket timeout');
  socket.end();
});
copy

如果 timeout 為 0，則停用現有的閒置逾時。

選用的 callback 參數將被新增為 'timeout' 事件的一次性接聽程式。

socket.getTypeOfService()#

• 返回：<integer> 目前的 TOS 值。

返回此通訊端目前 IPv4 封包的服務類型 (TOS) 欄位或 IPv6 封包的流量類別 (Traffic Class)。

setTypeOfService() 可以在通訊端連接之前呼叫；該值將被快取並在通訊端建立連線時套用。getTypeOfService() 即使在連接之前也會返回目前設定的值。

在某些平台 (例如 Linux) 上，某些 TOS/ECN 位元可能會被遮罩或忽略，且 IPv4 與 IPv6 或雙堆疊通訊端之間的行為可能有所不同。呼叫者應驗證特定平台的語義。

socket.setTypeOfService(tos)#

• tos <integer> 要設定的 TOS 值 (0-255)。
• 返回：<net.Socket> 通訊端本身。

設定從此通訊端發送的 IPv4 封包的服務類型 (TOS) 欄位或 IPv6 封包的流量類別。這可用於排定網路流量的優先順序。

setTypeOfService() 可以在通訊端連接之前呼叫；該值將被快取並在通訊端建立連線時套用。getTypeOfService() 即使在連接之前也會返回目前設定的值。

在某些平台 (例如 Linux) 上，某些 TOS/ECN 位元可能會被遮罩或忽略，且 IPv4 與 IPv6 或雙堆疊通訊端之間的行為可能有所不同。呼叫者應驗證特定平台的語義。

socket.timeout#

• 類型：<number> | <undefined>

由 socket.setTimeout() 設定的通訊端逾時時間 (以毫秒為單位)。如果未設定逾時，則為 undefined。

socket.unref()#

• 返回：<net.Socket> 通訊端本身。

在通訊端上呼叫 unref()，如果這是事件系統中唯一活躍的通訊端，將允許程式退出。如果通訊端已經 unref，再次呼叫 unref() 將沒有效果。

socket.write(data[, encoding][, callback])#

• data <string> | <Buffer> | <Uint8Array>
• encoding <string> 僅在資料為 string 時使用。預設值： utf8。
• callback <Function>
• 傳回：<boolean>

在通訊端上發送資料。第二個參數指定字串的編碼。預設為 UTF8 編碼。

如果所有資料都成功排清 (flushed) 到核心緩衝區，則返回 true。如果全部或部分資料在使用者記憶體中排隊，則返回 false。當緩衝區再次釋放時，將觸發 'drain' 事件。

選用的 callback 參數將在資料最終寫出時執行，這可能不會立即發生。

詳細資訊請參閱 Writable 串流的 write() 方法。

socket.readyState#

• 類型：<string>

此屬性以字串形式表示連線的狀態。

• 如果串流正在連接，則 socket.readyState 為 opening。
• 如果串流可讀且可寫，則為 open。
• 如果串流可讀但不可寫，則為 readOnly。
• 如果串流不可讀但可寫，則為 writeOnly。

net.connect()#

net.createConnection() 的別名。

可能的簽署方式：

• net.connect(options[, connectListener])
• 用於 IPC 連線的 net.connect(path[, connectListener])。
• 用於 TCP 連線的 net.connect(port[, host][, connectListener])。

net.connect(options[, connectListener])#

• options <Object>
• connectListener <Function>
• 返回：<net.Socket>

呼叫 net.createConnection(options[, connectListener]) 的別名。

net.connect(path[, connectListener])#

• path <string>
• connectListener <Function>
• 返回：<net.Socket>

呼叫 net.createConnection(path[, connectListener]) 的別名。

net.connect(port[, host][, connectListener])#

• port <number>
• host <string>
• connectListener <Function>
• 返回：<net.Socket>

呼叫 net.createConnection(port[, host][, connectListener]) 的別名。

net.createConnection()#

一個工廠函式，用於建立一個新的 net.Socket，立即使用 socket.connect() 啟動連線，然後返回啟動連線的 net.Socket。

建立連線時，會在返回的通訊端上觸發 'connect' 事件。最後一個參數 connectListener (如果提供) 將被新增為 'connect' 事件的一次性接聽程式。

可能的簽署方式：

• net.createConnection(options[, connectListener])
• 用於 IPC 連線的 net.createConnection(path[, connectListener])。
• 用於 TCP 連線的 net.createConnection(port[, host][, connectListener])。

net.connect() 函式是此函式的別名。

net.createConnection(options[, connectListener])#

• options <Object> 必填。將會被傳遞給 new net.Socket([options]) 呼叫以及 socket.connect(options[, connectListener]) 方法。
• connectListener <Function> net.createConnection() 函式的通用參數。如果提供，將會作為一次性監聽器新增到回傳 Socket 的 'connect' 事件上。
• 回傳：<net.Socket> 用於啟動連線的新建立 Socket。

有關可用的選項，請參閱 new net.Socket([options]) 和 socket.connect(options[, connectListener])。

額外選項

• timeout <number> 如果設定，將在 Socket 建立後但在啟動連線之前，用於呼叫 socket.setTimeout(timeout)。

以下是 net.createServer() 章節中所述 echo 伺服器的客戶端範例

import net from 'node:net';
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});
const net = require('node:net');
const client = net.createConnection({ port: 8124 }, () => {
  // 'connect' listener.
  console.log('connected to server!');
  client.write('world!\r\n');
});
client.on('data', (data) => {
  console.log(data.toString());
  client.end();
});
client.on('end', () => {
  console.log('disconnected from server');
});
copy

連線至 Socket /tmp/echo.sock

const client = net.createConnection({ path: '/tmp/echo.sock' });
copy

以下是使用 port 與 onread 選項的客戶端範例。在此情況下，onread 選項僅用於呼叫 new net.Socket([options])，而 port 選項則用於呼叫 socket.connect(options[, connectListener])。

import net from 'node:net';
import { Buffer } from 'node:buffer';
net.createConnection({
  port: 8124,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});
const net = require('node:net');
net.createConnection({
  port: 8124,
  onread: {
    // Reuses a 4KiB Buffer for every read from the socket.
    buffer: Buffer.alloc(4 * 1024),
    callback: function(nread, buf) {
      // Received data is available in `buf` from 0 to `nread`.
      console.log(buf.toString('utf8', 0, nread));
    },
  },
});
copy

net.createConnection(path[, connectListener])#

• path <string> Socket 應連線的路徑。將會傳遞給 socket.connect(path[, connectListener])。請參閱 識別 IPC 連線的路徑。
• connectListener <Function> net.createConnection() 函式的通用參數，啟動中 Socket 之 'connect' 事件的「一次性」監聽器。將會傳遞給 socket.connect(path[, connectListener])。
• 回傳：<net.Socket> 用於啟動連線的新建立 Socket。

啟動 IPC 連線。

此函式會建立一個所有選項皆為預設值的全新 net.Socket，隨即以 socket.connect(path[, connectListener]) 啟動連線，然後回傳啟動連線的 net.Socket。

net.createConnection(port[, host][, connectListener])#

• port <number> Socket 應連線的埠號。將會傳遞給 socket.connect(port[, host][, connectListener])。
• host <string> Socket 應連線的主機。將會傳遞給 socket.connect(port[, host][, connectListener])。預設值： 'localhost'。
• connectListener <Function> net.createConnection() 函式的通用參數，啟動中 Socket 之 'connect' 事件的「一次性」監聽器。將會傳遞給 socket.connect(port[, host][, connectListener])。
• 回傳：<net.Socket> 用於啟動連線的新建立 Socket。

啟動 TCP 連線。

此函式會建立一個所有選項皆為預設值的全新 net.Socket，隨即以 socket.connect(port[, host][, connectListener]) 啟動連線，然後回傳啟動連線的 net.Socket。

net.createServer([options][, connectionListener])#

• options <Object>

  • allowHalfOpen <boolean> 如果設為 false，當可讀取端結束時，Socket 將自動結束可寫入端。預設值： false。
  • highWaterMark <number> 選項式覆寫所有 net.Socket 的 readableHighWaterMark 與 writableHighWaterMark。預設值： 請參閱 stream.getDefaultHighWaterMark()。
  • keepAlive <boolean> 如果設為 true，則在接收到新的連入連線後立即在 Socket 上啟用 keep-alive 功能，類似於 socket.setKeepAlive() 的操作。預設值： false。
  • keepAliveInitialDelay <number> 如果設為正數，它會設定在閒置 socket 上發送第一個 keepalive 探測之前的初始延遲。預設值： 0。
  • noDelay <boolean> 如果設為 true，則在接收到新的連入連線後立即停用 Nagle 演算法。預設值： false。
  • pauseOnConnect <boolean> 指示是否應在連入連線時暫停 Socket。 預設值： false。
  • blockList <net.BlockList> blockList 可用於停用特定 IP 地址、IP 範圍或 IP 子網的連入存取。如果伺服器位於反向代理、NAT 等之後，則此功能無效，因為檢查封鎖清單的地址是代理伺服器的地址或由 NAT 指定的地址。

• connectionListener <Function> 自動設定為 'connection' 事件的接聽程式。

• 返回：<net.Server>

建立一個全新的 TCP 或 IPC 伺服器。

如果 allowHalfOpen 設為 true，當 Socket 的另一端發出傳輸結束訊號時，只有在明確呼叫 socket.end() 時，伺服器才會回傳傳輸結束訊號。例如，在 TCP 語境下，當接收到 FIN 封包時，只有在明確呼叫 socket.end() 時才會回傳 FIN 封包。在此之前，連線處於半關閉狀態（不可讀但仍可寫）。請參閱 'end' 事件與 RFC 1122 (第 4.2.2.13 節) 以取得更多資訊。

如果 pauseOnConnect 設為 true，則與每個連入連線相關聯的 Socket 都將暫停，且不會從其控制代碼 (handle) 讀取任何資料。這允許在程序之間傳遞連線，而原始程序不會讀取任何資料。要開始從暫停的 Socket 讀取資料，請呼叫 socket.resume()。

伺服器可以是 TCP 伺服器或 IPC 伺服器，取決於其 listen() 的對象。

以下是一個 TCP echo 伺服器的範例，它在埠號 8124 監聽連線：

import net from 'node:net';
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});
const net = require('node:net');
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');
  c.pipe(c);
});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});
copy

使用 telnet 進行測試：

telnet localhost 8124
copy

連線至 Socket /tmp/echo.sock

server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});
copy

使用 nc 連線至 Unix 網域 Socket 伺服器：

nc -U /tmp/echo.sock
copy

net.getDefaultAutoSelectFamily()#

獲取 socket.connect(options) 的 autoSelectFamily 選項之當前預設值。初始預設值為 true，除非提供了命令列選項 --no-network-family-autoselection。

• 回傳：<boolean> autoSelectFamily 選項的目前預設值。

net.setDefaultAutoSelectFamily(value)#

設定 socket.connect(options) 的 autoSelectFamily 選項之預設值。

• value <boolean> 新的預設值。初始預設值為 true，除非提供了命令列選項 --no-network-family-autoselection。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

獲取 socket.connect(options) 的 autoSelectFamilyAttemptTimeout 選項之當前預設值。初始預設值為 500 或透過命令列選項 --network-family-autoselection-attempt-timeout 指定的值。

• 回傳：<number> autoSelectFamilyAttemptTimeout 選項的目前預設值。

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

設定 socket.connect(options) 的 autoSelectFamilyAttemptTimeout 選項之預設值。

• value <number> 新的預設值，必須是正數。如果數字小於 10，則改用值 10。初始預設值為 250 或透過命令列選項 --network-family-autoselection-attempt-timeout 指定的值。

net.isIP(input)#

• input <string>
• 回傳：<integer>

如果 input 是 IPv6 地址，則回傳 6。如果 input 是不含前導零的點分十進位標法 IPv4 地址，則回傳 4。否則回傳 0。

net.isIP('::1'); // returns 6
net.isIP('127.0.0.1'); // returns 4
net.isIP('127.000.000.001'); // returns 0
net.isIP('127.0.0.1/24'); // returns 0
net.isIP('fhqwhgads'); // returns 0
copy

net.isIPv4(input)#

• input <string>
• 傳回：<boolean>

如果 input 是不含前導零的點分十進位標法 IPv4 地址，則回傳 true。否則回傳 false。

net.isIPv4('127.0.0.1'); // returns true
net.isIPv4('127.000.000.001'); // returns false
net.isIPv4('127.0.0.1/24'); // returns false
net.isIPv4('fhqwhgads'); // returns false
copy

net.isIPv6(input)#

• input <string>
• 傳回：<boolean>

如果 input 是 IPv6 地址，則回傳 true。否則回傳 false。

net.isIPv6('::1'); // returns true
net.isIPv6('fhqwhgads'); // returns false
copy