Node.js v21.7.2 文件

IPC 支援#

node:net 模組支援 Windows 上的命名管線 IPC，以及其他作業系統上的 Unix 域套接字。

識別 IPC 連線路徑#

net.connect()、net.createConnection()、server.listen() 和 socket.connect() 採用 path 參數來辨識 IPC 端點。

在 Unix 上，本機網域也稱為 Unix 網域。路徑是檔案系統路徑名稱。它會被截斷為作業系統相關的長度 sizeof(sockaddr_un.sun_path) - 1。典型的值在 Linux 上為 107 位元組，在 macOS 上為 103 位元組。如果 Node.js API 抽象建立 Unix 網域 socket，它也會取消連結 Unix 網域 socket。例如，net.createServer() 可能建立 Unix 網域 socket，而 server.close() 會取消連結它。但如果使用者在這些抽象之外建立 Unix 網域 socket，使用者需要移除它。當 Node.js API 建立 Unix 網域 socket 但程式隨後當機時，也會套用相同的原則。簡而言之，Unix 網域 socket 會在檔案系統中顯示，並持續存在直到取消連結。在 Linux 上，您可以透過在路徑開頭加入 \0 來使用 Unix 抽象 socket，例如 \0abstract。Unix 抽象 socket 的路徑在檔案系統中不會顯示，且當所有開啟的 socket 參照關閉時，它會自動消失。

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

JavaScript 字串跳脫需要使用額外的反斜線跳脫來指定路徑，例如

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 <字串> | <net.SocketAddress> 網路 IPv4 或 IPv6 位址。
• prefix <數字> CIDR 前置位元數。對於 IPv4，此值必須介於 0 和 32 之間。對於 IPv6，此值必須介於 0 和 128 之間。
• type <string> 'ipv4' 或 'ipv6'。預設：'ipv4'。

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

blockList.check(address[, type])#

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

如果指定的 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#

• 類型：<字串陣列>

新增至封鎖清單的規則清單。

類別：net.SocketAddress#

new net.SocketAddress([options])#

• options <物件>
  • address <字串> 網路地址，可以是 IPv4 或 IPv6 字串。預設值：如果 family 是 'ipv4'，則為 '127.0.0.1'；如果 family 是 'ipv6'，則為 '::'。
  • family <字串> 'ipv4' 或 'ipv6' 之一。預設值：'ipv4'。
  • flowlabel <數字> 僅在 family 是 'ipv6' 時使用的 IPv6 流標籤。
  • port <數字> IP 埠。

socketaddress.address#

• 類型 <字串>

socketaddress.family#

• 類型 <字串> 'ipv4' 或 'ipv6'。

socketaddress.flowlabel#

• 類型 <數字>

socketaddress.port#

• 類型 <數字>

類別：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 不同，'close' 事件在這個事件之後不會直接觸發，除非手動呼叫 server.close()。請參閱 server.listen() 討論中的範例。

事件：'listening'#

呼叫 server.listen() 之後，伺服器繫結時觸發。

事件：'drop'#

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

• data <物件> 傳遞給事件偵聽器的引數。
  • localAddress <字串> 本機位址。
  • localPort <數字> 本機埠。
  • localFamily <字串> 本機系列。
  • remoteAddress <字串> 遠端位址。
  • remotePort <數字> 遠端埠。
  • remoteFamily <字串> 遠端 IP 系列。'IPv4' 或 'IPv6'。

server.address()#

• 傳回：<物件> | <字串> | <null>

傳回繫結的 address、family 名稱，以及作業系統所回報的伺服器 port（在 IP socket 上偵聽時很有用，用於尋找在取得作業系統所指定位址時指定了哪個埠）：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }。

對於在管線或 Unix 域 socket 上偵聽的伺服器，名稱會傳回為字串。

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

server.address() 在發出 'listening' 事件或呼叫 server.close() 之後傳回 null。

server.close([callback])#

• 回呼 <函式> 伺服器關閉時呼叫。
• 傳回：<net.Server>

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

server[Symbol.asyncDispose]()#

呼叫 server.close()，並傳回一個在伺服器關閉時會兌現的承諾。

server.getConnections(callback)#

• 回呼 <函式>
• 傳回：<net.Server>

非同步取得伺服器上的並發連線數。在將 socket 傳送至 fork 時運作。

回呼應採用兩個引數 err 和 count。

server.listen()#

啟動伺服器偵聽連線。net.Server 可以是 TCP 或 IPC 伺服器，視其偵聽的內容而定。

可能的簽章

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

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

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

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

server.listen() 方法只能在第一次 server.listen() 呼叫期間發生錯誤或已呼叫 server.close() 時再次呼叫。否則，將會擲回 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() 函式的共用參數
• 回呼 <函式>
• 傳回：<net.Server>

啟動伺服器監聽已繫結至埠、Unix 域套接字或 Windows 命名管道的特定 handle 上的連線。

handle 物件可以是伺服器、套接字（任何具有基礎 _handle 成員的物件）或具有 fd 成員（有效檔案描述子）的物件。

Windows 不支援在檔案描述符上進行監聽。

server.listen(options[, callback])#

• options <Object> 必要。支援下列屬性
  • port <number>
  • host <string>
  • path <string> 如果指定 port，將會略過。請參閱 識別 IPC 連線路徑。
  • backlog <number> server.listen() 函式的共用參數。
  • exclusive <boolean> 預設值： false
  • readableAll <boolean> 對於 IPC 伺服器，讓所有使用者都可以讀取管線。預設值： false。
  • writableAll <boolean> 對於 IPC 伺服器，讓所有使用者都可以寫入管線。預設值： false。
  • ipv6Only <boolean> 對於 TCP 伺服器，將 ipv6Only 設定為 true 會停用雙堆疊支援，也就是說，繫結到主機 :: 時不會繫結到 0.0.0.0。預設值： false。
  • signal <AbortSignal> 可用於關閉監聽伺服器的 AbortSignal。
• callback <Function> 函式。
• 傳回：<net.Server>

如果指定了 port，則其行為與 server.listen([port[, host[, backlog]]][, callback]) 相同。否則，如果指定了 path，則其行為與 server.listen(path[, backlog][, callback]) 相同。如果未指定任何一個，則會擲回錯誤。

如果 exclusive 為 false（預設），則叢集工作執行緒將使用相同的底層控制代碼，允許共用連線處理任務。當 exclusive 為 true 時，不共用控制代碼，而嘗試共用埠會導致錯誤。以下所示範例會在獨佔埠上監聽。

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

當 exclusive 為 true 且共用底層控制代碼時，有可能會有數個工作執行緒查詢具有不同未處理請求數量的控制代碼。在此情況下，將使用傳遞給主程序的第一個 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>

啟動 IPC 伺服器，在指定的 path 上監聽連線。

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>

當伺服器連線數過高時，設定此屬性以拒絕連線。

不建議在使用 child_process.fork() 將 socket 傳送給子程序後使用此選項。

server.ref()#

• 傳回：<net.Server>

與 unref() 相反，在先前已 unref 的伺服器上呼叫 ref() 將不會讓程式退出，如果它是唯一剩餘的伺服器（預設行為）。如果伺服器已 ref，再次呼叫 ref() 將不會產生任何效果。

server.unref()#

• 傳回：<net.Server>

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

類別：net.Socket#

• 延伸：<stream.Duplex>

此類別是 TCP socket 或串流 IPC 端點（在 Windows 上使用命名管線，否則使用 Unix 域 socket）的抽象。它也是 EventEmitter。

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

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

new net.Socket([選項])#

• 選項 <物件> 可用的選項為
  • fd <數字> 如果有指定，則使用給定的檔案描述符封裝現有的 socket，否則將建立新的 socket。
  • allowHalfOpen <布林值> 如果設定為 false，則當可讀取端點結束時，socket 將自動結束可寫入端點。有關詳細資訊，請參閱 net.createServer() 和 'end' 事件。預設值： false。
  • readable <布林值> 當傳遞 fd 時允許在 socket 上讀取，否則忽略。預設值： false。
  • writable <布林值> 當傳遞 fd 時允許在 socket 上寫入，否則忽略。預設值： false。
  • signal <中斷訊號> 可用於銷毀 socket 的中斷訊號。
• 傳回：<net.Socket>

建立新的 socket 物件。

新建立的 socket 可以是 TCP socket 或串流 IPC 端點，視其 connect() 的對象而定。

事件：'close'#

• hadError <布林值> 如果 socket 發生傳輸錯誤，則為 true。

當 socket 完全關閉時發出。參數 hadError 是布林值，表示 socket 是否因傳輸錯誤而關閉。

事件：'connect'#

當 socket 連線成功建立時發出。請參閱 net.createConnection()。

事件：'connectionAttempt'#

• ip <字串> socket 嘗試連線的 IP。
• port <數字> socket 嘗試連線的埠。
• family <數字> IP 的家族。可能是 IPv6 的 6 或 IPv4 的 4。

當新的連線嘗試開始時發出。如果在 socket.connect(options) 中啟用家族自動選取演算法，可能會發出多次。

事件：'connectionAttemptFailed'#

• ip <字串> socket 嘗試連線的 IP。
• port <數字> socket 嘗試連線的埠。
• family <數字> IP 的家族。可能是 IPv6 的 6 或 IPv4 的 4。*nbsp;error <錯誤> 與失敗相關的錯誤。

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

事件：'connectionAttemptTimeout'#

• ip <字串> socket 嘗試連線的 IP。
• port <數字> socket 嘗試連線的埠。
• family <數字> IP 的家族。可能是 IPv6 的 6 或 IPv4 的 4。

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

事件：'data'#

• <Buffer> | <string>

接收資料時發出。引數 data 將會是 Buffer 或 String。資料編碼由 socket.setEncoding() 設定。

當 Socket 發出 'data' 事件時，若沒有監聽器，資料將會遺失。

事件：'drain'#

寫入緩衝區清空時發出。可用於限制上傳速度。

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

事件：'end'#

當 Socket 的另一端傳送傳輸結束訊號時發出，進而結束 Socket 的可讀取端。

預設（allowHalfOpen 為 false）Socket 會在寫出待寫佇列後，傳送傳輸結束封包並銷毀其檔案描述符。然而，如果 allowHalfOpen 設為 true，Socket 將不會自動 end() 其可寫入端，允許使用者寫入任意數量的資料。使用者必須明確呼叫 end() 來關閉連線（即傳送 FIN 封包）。

事件：'error'#

• <Error>

當發生錯誤時發出。'close' 事件將在這個事件之後立即呼叫。

事件：'lookup'#

在解析主機名稱後，但在連接之前發出。不適用於 Unix socket。

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

事件：'ready'#

當 socket 準備好使用時發出。

在 'connect' 之後立即觸發。

事件：'timeout'#

如果 socket 因閒置而逾時，則發出。這只是為了通知 socket 已閒置。使用者必須手動關閉連線。

另請參閱：socket.setTimeout()。

socket.address()#

• 傳回：<Object>

傳回作業系統回報的 socket 之繫結 address、family 名稱和 port：{ port: 12346, family: 'IPv4', address: '127.0.0.1' }

socket.autoSelectFamilyAttemptedAddresses#

• <string[]>

此屬性僅在 socket.connect(options) 中啟用 family 自動選取演算法時存在，且為已嘗試過的位址陣列。

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

socket.bufferSize#

• <integer>

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

net.Socket 具有 socket.write() 永遠有效的屬性。這是為了協助使用者快速上手。電腦無法總是跟上寫入 socket 的資料量。網路連線可能太慢。Node.js 會在內部將寫入 socket 的資料排隊，並在可能時透過網路傳送。

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

socket.bytesRead#

• <integer>

接收的位元組數。

socket.bytesWritten#

• <integer>

傳送的位元組數。

socket.connect()#

在特定 socket 上啟動連線。

可能的簽章

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

此函式為非同步。建立連線後，將會發出 'connect' 事件。如果連線有問題，則會發出 'error' 事件，並將錯誤傳遞給 'error' 監聽器，而不是 'connect' 事件。最後一個參數 connectListener（如果提供）將會新增為 'connect' 事件的監聽器一次。

此函式只能用於在發出 'close' 後重新連線 socket，否則可能會導致未定義的行為。

socket.connect(options[, connectListener])#

• options <物件>
• connectListener <Function> socket.connect() 方法的共通參數。會作為 'connect' 事件的監聽器新增一次。
• 傳回：<net.Socket> socket 本身。

在給定的 socket 上啟動連線。通常不需要這個方法，應該使用 net.createConnection() 建立並開啟 socket。只有在實作自訂 Socket 時才使用這個方法。

對於 TCP 連線，可用的 options 為

• port <number> 必填。socket 應連線的埠。
• host <string> socket 應連線的主機。預設值：'localhost'。
• localAddress <string> socket 應從中連線的本機地址。
• localPort <number> socket 應從中連線的本機埠。
• family <number>：IP 堆疊版本。必須為 4、6 或 0。值 0 表示允許 IPv4 和 IPv6 位址。預設：0。
• hints <number> 選擇性的 dns.lookup() 提示。
• lookup <Function> 自訂查詢函式。預設： dns.lookup()。
• noDelay <boolean> 如果設為 true，則在建立 socket 後立即停用 Nagle 演算法。預設：false。
• keepAlive <boolean> 如果設為 true，則在建立連線後立即在 socket 上啟用保持連線功能，類似於 socket.setKeepAlive([enable][, initialDelay]) 中執行的動作。預設：false。
• keepAliveInitialDelay <number> 如果設為正數，則設定在閒置 socket 上傳送第一個保持連線探測之前的初始延遲時間。預設：0。
• autoSelectFamily <布林值>: 如果設為 true，它會啟用一個家族自動偵測演算法，該演算法大致實作 RFC 8305 的第 5 節。傳遞給查詢的 all 選項設為 true，且套接字會嘗試依序連線至所有取得的 IPv6 和 IPv4 位址，直到建立連線為止。會先嘗試第一個傳回的 AAAA 位址，接著是第一個傳回的 A 位址，然後是第二個傳回的 AAAA 位址，以此類推。每次連線嘗試（但最後一次除外）會在逾時並嘗試下一個位址之前，給予由 autoSelectFamilyAttemptTimeout 選項指定的時間量。如果 family 選項不是 0 或已設定 localAddress，則會略過。如果至少有一個連線成功，則不會發出連線錯誤。如果所有連線嘗試都失敗，則會發出一個包含所有失敗嘗試的單一 AggregateError。預設值： net.getDefaultAutoSelectFamily()
• autoSelectFamilyAttemptTimeout <數字>: 使用 autoSelectFamily 選項時，在嘗試下一個位址之前，等待連線嘗試完成的時間量（毫秒）。如果設為小於 10 的正整數，則會改用值 10。預設值： net.getDefaultAutoSelectFamilyAttemptTimeout()

對於 IPC 連線，可用的 options 為

• path <字串> 必填。客戶端應連線到的路徑。請參閱 識別 IPC 連線的路徑。如果提供，則會略過上述 TCP 特定的選項。

對於這兩種類型，可用的 options 包括

• onread <Object> 如果指定，則會將接收到的資料儲存在單一 buffer 中，並在資料到達 socket 時傳遞給提供的 callback。這將導致串流功能不提供任何資料。Socket 會像往常一樣發出 'error'、'end' 和 'close' 等事件。pause() 和 resume() 等方法也會按預期執行。
  • buffer <Buffer> | <Uint8Array> | <Function> 可重複使用的記憶體區塊，用於儲存接收到的資料，或傳回此類資料的函式。
  • callback <Function> 這個函式會在接收到的每個資料區塊呼叫。會傳遞兩個參數給它：寫入 buffer 的位元組數和 buffer 的參考。從這個函式傳回 false 以隱式 pause() socket。這個函式會在全域背景中執行。

以下是使用 onread 選項的客戶端範例

const net = require('node:net');
net.connect({
  port: 80,
  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

socket.connect(path[, connectListener])#

• path <string> 客戶端應連線的路徑。請參閱 識別 IPC 連線路徑。
• connectListener <Function> socket.connect() 方法的共通參數。會作為 'connect' 事件的監聽器新增一次。
• 傳回：<net.Socket> socket 本身。

在指定的 socket 上啟動 IPC 連線。

別名為 socket.connect(options[, connectListener])，呼叫時使用 { path: path } 作為 options。

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

• port <數字> 伺服器連線的埠號。
• host <字串> 伺服器連線的主機名稱。
• connectListener <Function> socket.connect() 方法的共通參數。會作為 'connect' 事件的監聽器新增一次。
• 傳回：<net.Socket> socket 本身。

在給定的 socket 上啟動 TCP 連線。

別名為 socket.connect(options[, connectListener])，呼叫時將 {port: port, host: host} 作為 options。

socket.connecting#

• <布林值>

如果為 true，表示 socket.connect(options[, connectListener]) 已呼叫但尚未完成。它會保持為 true，直到 socket 連線完成，然後設定為 false 並發出 'connect' 事件。請注意，socket.connect(options[, connectListener]) 回呼是 'connect' 事件的監聽器。

socket.destroy([error])#

• error <物件>
• 傳回：<net.Socket>

確保此 socket 上不再發生 I/O 活動。摧毀串流並關閉連線。

詳情請參閱 writable.destroy()。

socket.destroyed#

• <布林值> 表示連線是否已摧毀。連線一旦摧毀，就無法再透過它傳輸資料。

詳情請參閱 writable.destroyed。

socket.destroySoon()#

在所有資料寫入後摧毀 socket。如果已發出 'finish' 事件，socket 會立即被摧毀。如果 socket 仍可寫入，它會隱含呼叫 socket.end()。

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

• data <字串> | <Buffer> | <Uint8Array>
• encoding <字串> 僅在資料為 字串 時使用。預設： 'utf8'。
• callback <函式> socket 完成時選用的 callback。
• 傳回：<net.Socket> socket 本身。

半關閉 socket。即，它會傳送 FIN 封包。伺服器仍有可能會傳送一些資料。

請參閱 writable.end() 以取得更多詳細資料。

socket.localAddress#

• <字串>

遠端用戶端連線的本機 IP 位址的字串表示。例如，在監聽 '0.0.0.0' 的伺服器中，如果用戶端連線到 '192.168.1.1'，socket.localAddress 的值會是 '192.168.1.1'。

socket.localPort#

• <integer>

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

socket.localFamily#

• <字串>

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

socket.pause()#

• 傳回：<net.Socket> socket 本身。

暫停讀取資料。也就是說，將不會發出 'data' 事件。對於限制上傳速度很有用。

socket.pending#

• <布林值>

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

socket.ref()#

• 傳回：<net.Socket> socket 本身。

與 unref() 相反，在先前已 unref 的套接字上呼叫 ref() 不會 讓程式在它是唯一剩餘的套接字時退出 (預設行為)。如果套接字已 ref，則再次呼叫 ref 不會產生任何效果。

socket.remoteAddress#

• <字串>

遠端 IP 位址的字串表示形式。例如，'74.125.127.100' 或 '2001:4860:a005::68'。如果套接字已銷毀 (例如，如果客戶端已中斷連線)，則值可能是 undefined。

socket.remoteFamily#

• <字串>

遠端 IP 家族的字串表示形式。'IPv4' 或 'IPv6'。如果套接字已銷毀 (例如，如果客戶端已中斷連線)，則值可能是 undefined。

socket.remotePort#

• <integer>

遠端埠口的數字表示形式。例如，80 或 21。如果套接字已銷毀 (例如，如果客戶端已中斷連線)，則值可能是 undefined。

socket.resetAndDestroy()#

• 傳回：<net.Socket>

透過傳送 RST 封包來關閉 TCP 連線，並銷毀串流。如果此 TCP socket 處於連線狀態，它將傳送 RST 封包並在連線後銷毀此 TCP socket。否則，它將呼叫 socket.destroy，並附帶 ERR_SOCKET_CLOSED 錯誤。如果這不是 TCP socket（例如管線），呼叫此方法將立即擲回 ERR_INVALID_HANDLE_TYPE 錯誤。

socket.resume()#

• 傳回：<net.Socket> socket 本身。

在呼叫 socket.pause() 之後繼續讀取。

socket.setEncoding([encoding])#

• encoding <string>
• 傳回：<net.Socket> socket 本身。

將 socket 的編碼設定為 可讀取串流。請參閱 readable.setEncoding() 以取得更多資訊。

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

• enable <boolean> 預設值： false
• initialDelay <number> 預設值： 0
• 傳回：<net.Socket> socket 本身。

啟用/停用保持連線功能，並選擇性地設定在閒置 socket 上傳送第一個保持連線探測之前的第一個延遲時間。

設定 initialDelay（以毫秒為單位）以設定接收最後一個資料封包和第一個保持連線探測之間的延遲時間。將 initialDelay 設定為 0 會將值保留為預設值（或前一個）設定。

啟用保持連線功能會設定下列 socket 選項

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

socket.setNoDelay([noDelay])#

• noDelay <布林值> 預設值： true
• 傳回：<net.Socket> socket 本身。

啟用/停用 Nagle 演算法。

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

Nagle 演算法會延遲資料透過網路傳送。它會嘗試以延遲為代價來最佳化傳輸量。

傳遞 true 給 noDelay 或不傳遞引數會停用 socket 的 Nagle 演算法。傳遞 false 給 noDelay 會啟用 Nagle 演算法。

socket.setTimeout(timeout[, callback])#

• timeout <數字>
• 回呼 <函式>
• 傳回：<net.Socket> socket 本身。

設定 socket 在 socket 上閒置 timeout 毫秒後逾時。預設 net.Socket 沒有逾時。

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

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

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

可以將選用的 callback 參數新增為 'timeout' 事件的一次性監聽器。

socket.timeout#

• <number> | <undefined>

由 socket.setTimeout() 設定的套接字逾時時間（毫秒）。如果尚未設定逾時時間，則為 undefined。

socket.unref()#

• 傳回：<net.Socket> socket 本身。

在套接字上呼叫 unref() 將允許程式退出，如果這是事件系統中唯一活動的套接字。如果套接字已經 unref，則再次呼叫 unref() 將不會產生任何效果。

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

• data <字串> | <Buffer> | <Uint8Array>
• encoding <string> 僅在資料為 string 時使用。預設值：utf8。
• 回呼 <函式>
• 傳回：<布林值>

在套接字上傳送資料。第二個參數指定字串的編碼。預設為 UTF8 編碼。

如果已成功將所有資料快取至核心緩衝區，則傳回 true。如果部分或全部資料已排入使用者記憶體，則傳回 false。當緩衝區再次釋放時，將會發出 'drain'。

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

請參閱 Writable 串流 write() 方法以取得更多資訊。

socket.readyState#

• <字串>

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

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

net.connect()#

別名為 net.createConnection()。

可能的簽章

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

net.connect(options[, connectListener])#

• options <物件>
• 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。

建立連線時，傳回的 socket 會發出 'connect' 事件。最後一個參數 connectListener（如果提供）會被加入為 'connect' 事件的監聽器，僅一次。

可能的簽章

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

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() 區段中所述迴音伺服器的客戶端範例

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

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 <物件>

  • allowHalfOpen <boolean> 如果設定為 false，則當可讀取端結束時，Socket 會自動結束可寫入端。預設值：false。
  • highWaterMark <number> 選擇性覆寫所有 net.Socket 的 readableHighWaterMark 和 writableHighWaterMark。預設值：請參閱 stream.getDefaultHighWaterMark()。
  • pauseOnConnect <布林值> 指出是否應在連線進來時暫停 socket。預設：false。
  • noDelay <布林值> 如果設為 true，它會在收到新的連線後立即停用 Nagle 演算法。預設：false。
  • keepAlive <布林值> 如果設為 true，它會在收到新的連線後立即在 socket 上啟用保持連線功能，類似於 socket.setKeepAlive([enable][, initialDelay]) 中所做的。預設：false。
  • keepAliveInitialDelay <number> 如果設為正數，則設定在閒置 socket 上傳送第一個保持連線探測之前的初始延遲時間。預設：0。

• 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 將會暫停，且不會從其處理中讀取任何資料。這允許在處理之間傳遞連線，而不會讓原始處理讀取任何資料。若要開始從暫停的 socket 讀取資料，請呼叫 socket.resume()。

伺服器可以是 TCP 伺服器或 IPC 伺服器，這取決於它 listen() 的內容。

以下是 TCP 回應伺服器的範例，它會在埠 8124 上偵聽連線

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 選項的目前預設值。除非提供命令列選項 --no-network-family-autoselection，否則初始預設值為 true。

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

net.setDefaultAutoSelectFamily(value)#

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

• value <boolean> 新的預設值。初始預設值為 false。

net.getDefaultAutoSelectFamilyAttemptTimeout()#

取得 socket.connect(options) 的 autoSelectFamilyAttemptTimeout 選項的目前預設值。初始預設值為 250。

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

net.setDefaultAutoSelectFamilyAttemptTimeout(value)#

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

• value <數字> 新的預設值，必須是正數。如果數字小於 10，則改用 10。初始預設值為 250。

net.isIP(input)#

• input <字串>
• 傳回：<整數>

如果 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 <字串>
• 傳回：<布林值>

如果 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 <字串>
• 傳回：<布林值>

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

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