Node.js v25.0.0 文件

識別 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 域套接字，它也會取消連結該 Unix 域套接字。例如，net.createServer() 可能會建立一個 Unix 域套接字，而 server.close() 會取消連結它。但如果使用者在這些抽象之外建立了 Unix 域套接字，使用者將需要自己移除它。當 Node.js API 建立了一個 Unix 域套接字但程式隨後崩潰時，也適用同樣的情況。簡而言之，一個 Unix 域套接字將在檔案系統中可見，並會一直存在直到被取消連結。在 Linux 上，你可以透過在路徑開頭新增 \0 來使用 Unix 抽象套接字，例如 \0abstract。Unix 抽象套接字的路徑在檔案系統中不可見，當所有對該套接字的開啟引用都關閉時，它將自動消失。

在 Windows 上，本地域是使用命名管道實現的。路徑必須指向 \\?\pipe\ 或 \\.\pipe\ 中的一個條目。允許任何字元，但後者可能會對管道名稱進行一些處理，例如解析 .. 序列。儘管看起來可能不是這樣，但管道名稱空間是扁平的。管道將不會持久化。當對它們的最後一個引用關閉時，它們會被移除。與 Unix 域套接字不同，Windows 會在所屬程序退出時關閉並移除管道。

JavaScript 字串轉義要求路徑使用額外的反斜槓進行轉義，例如

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

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

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> IPv6 流標籤，僅當 family 為 '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。

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（用於查詢獲取作業系統分配的地址時分配的埠）：{ 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' 事件時，伺服器最終關閉。可選的 callback 將在 'close' 事件發生時被呼叫一次。與該事件不同，如果伺服器在關閉時未開啟，它將以一個 Error 作為其唯一引數被呼叫。

server[Symbol.asyncDispose]()#

呼叫 server.close() 並返回一個 Promise，該 Promise 在伺服器關閉時兌現。

server.getConnections(callback)#

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

非同步獲取伺服器上的併發連線數。在套接字被髮送到子程序時也有效。

回撥函式應接受兩個引數 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.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({
  host: 'localhost',
  port: 80,
  exclusive: true,
}); copy

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.listening#

• 型別：<boolean> 表示伺服器是否正在監聽連線。

server.maxConnections#

• 型別：<integer>

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

1. 如果程序不是在叢集模式下執行，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() 將沒有效果。

new net.Socket([options])#

• options <Object> 可用選項有
  • allowHalfOpen <boolean> 如果設定為 false，則當可讀端結束時，套接字將自動結束可寫端。詳情請參閱 net.createServer() 和 'end' 事件。預設值： false。
  • fd <number> 如果指定，則包裝一個具有給定檔案描述符的現有套接字，否則將建立一個新套接字。
  • 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 訊號。
  • 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])
• socket.connect(path[, connectListener]) 用於 IPC 連線。
• socket.connect(port[, host][, connectListener]) 用於 TCP 連線。
• 返回：<net.Socket> 套接字本身。

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

此函式只應用於在 'close' 事件觸發後重新連線套接字，否則可能導致未定義行為。

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> 套接字本身。

半關閉套接字。即，它傳送一個 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.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 編碼。

如果全部資料已成功重新整理到核心緩衝區，則返回 true。如果全部或部分資料已在使用者記憶體中排隊，則返回 false。當緩衝區再次空閒時，將觸發 'drain' 事件。

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

更多資訊請參見 Writable 流的 write() 方法。

socket.readyState#

• 型別：<string>

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

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

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(options[, connectListener])#

• options <Object> 必需。此物件會同時傳遞給 new net.Socket([options]) 呼叫和 socket.connect(options[, connectListener]) 方法。
• connectListener <Function> net.createConnection() 函式的通用引數。如果提供，它將被新增為返回的套接字上 'connect' 事件的一次性監聽器。
• 返回: <net.Socket> 用於啟動連線的新建立的套接字。

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

附加選項

• timeout <number> 如果設定，將在套接字建立之後、開始連線之前，用於呼叫 socket.setTimeout(timeout)。

以下是 net.createServer() 部分中描述的回顯伺服器的客戶端示例：

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

連線到套接字 /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.connect(path[, connectListener])。請參閱識別 IPC 連線的路徑。
• connectListener <Function> net.createConnection() 函式的通用引數，是發起連線的套接字上 'connect' 事件的“一次性”監聽器。將被傳遞給 socket.connect(path[, connectListener])。
• 返回: <net.Socket> 用於啟動連線的新建立的套接字。

發起一個 IPC 連線。

此函式建立一個新的 net.Socket，所有選項都設定為預設值，並立即透過 socket.connect(path[, connectListener]) 發起連線，然後返回啟動連線的 net.Socket。

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

• port <number> 套接字應連線的埠。將被傳遞給 socket.connect(port[, host][, connectListener])。
• host <string> 套接字應連線的主機。將被傳遞給 socket.connect(port[, host][, connectListener])。預設值: 'localhost'。
• connectListener <Function> net.createConnection() 函式的通用引數，是發起連線的套接字上 'connect' 事件的“一次性”監聽器。將被傳遞給 socket.connect(port[, host][, connectListener])。
• 返回: <net.Socket> 用於啟動連線的新建立的套接字。

發起一個 TCP 連線。

此函式建立一個新的 net.Socket，所有選項都設定為預設值，並立即透過 socket.connect(port[, host][, connectListener]) 發起連線，然後返回啟動連線的 net.Socket。