NodeJS 8 ，從 0 到 1：npm 包發布與更新全流程指南（含多場景適配與踩坑總結）

前言

在現代前端和 Node.js 開發中，npm（Node Package Manager）已經成為 JavaScript 生態系統中最重要的包管理工具之一。無論是開源項目還是公司內部的私有項目，npm 都扮演著至關重要的角色。

對于許多開發者而言，將自己的代碼打包發布到 npm，不僅可以方便復用，還能讓團隊或社區更輕松地共享代碼。然而，第一次嘗試發布 npm 包時，常常會遇到一些問題，比如登錄失敗、registry 配置錯誤、包名沖突等。

本文將詳細介紹從 零開始發布一個 npm 包 的完整流程，并深入分析常見問題，例如 Public registration is not allowed 報錯的原因及解決方案。無論你是初次接觸 npm 包發布的新手，還是想系統梳理流程的老手，都可以通過本文找到清晰的參考步驟，幫助你快速掌握 npm 包從 0 到 1 的落地能力。

一、準備工作

npm 包開發前的準備工作：在編寫代碼前，需完成環境搭建、賬號配置與項目初始化，這是確保后續流程順利的基礎。

1.1 開發環境搭建

npm 包依賴 Node.js 運行環境（npm 隨 Node.js 自帶），需先完成環境配置與驗證。

1.1.1 環境安裝

安裝 Node.js 與 npm

下載渠道：訪問Node.js 官網，根據操作系統（Windows/macOS/Linux）選擇 LTS 版本（長期支持版，穩定性更高）下載安裝。
版本要求：建議 Node.js 版本≥14.x，npm 版本≥6.x（可通過node -v和npm -v命令驗證安裝結果）。
示例：
bash
```
# 驗證Node.js版本
node -v  # 輸出 v18.17.0（示例版本）# 驗證npm版本
npm -v   # 輸出 9.6.7（示例版本）
```

1.1.2 配置問題

鏡像源配置（避坑關鍵）：

國內開發者常因網絡問題使用第三方鏡像源（如淘寶鏡像https://registry.npmmirror.com）加速依賴下載，但登錄 npm 與發布包時必須切換回官方源，否則會出現 “Public registration is not allowed”“登錄失敗” 等報錯。

查看當前鏡像源：
bash
```
npm config get registry
```

臨時切換官方源（發布時使用）：

bash

npm config set registry https://registry.npmjs.org/

發布后恢復鏡像源（可選，不影響后續開發）：
bash
```
npm config set registry https://registry.npmmirror.com
```

1.2 賬號注冊

npm 賬號注冊與配置：npm 包的發布與管理依賴獨立的 npm 賬號，需完成注冊、郵箱驗證與個人信息配置（含頭像設置）。

1.2.1 賬號注冊（兩種方式）

npm 賬號支持 “網頁注冊” 與 “CLI 注冊”，若網頁注冊頁面（https://www.npmjs.com/signup）解析失敗，可通過 CLI 方式注冊。

方式 1：網頁注冊
1. 訪問：https://www.npmjs.com/signup，輸入用戶名（唯一，后續不可修改）、郵箱（需驗證）、密碼（建議包含大小寫 + 數字 + 特殊符號）。
2. 注冊后，登錄注冊郵箱，點擊 npm 發送的驗證鏈接完成激活（未驗證郵箱無法登錄與發布包）。
方式 2：CLI 注冊（網絡異常時備選）
在終端執行以下命令，按提示輸入信息，無需訪問網頁：

bash
```
npm adduser
# 依次輸入：npm用戶名 → 郵箱 → 密碼 → 郵箱驗證碼（若觸發）
```

1.2.2 登錄驗證

賬號登錄驗證：注冊并激活后，需在本地終端登錄 npm 賬號，確保后續發布權限：

bash

# 執行登錄命令
npm login
# 輸入信息：
# Username: 你的npm用戶名
# Password: 你的npm密碼（輸入時不顯示，輸完按回車）
# Email: (this IS public) 你的注冊郵箱
# Enter one-time password from your authenticator app: 若開啟2FA，輸入動態驗證碼

登錄成功驗證：執行npm whoami，若輸出你的 npm 用戶名，說明登錄成功；若提示 “Not logged in”，需重新檢查賬號密碼或郵箱驗證狀態。

1.2.3 個人設置

個人信息與頭像設置：npm 頭像支持 “本地上傳” 或 “關聯 Gravatar”，后者可實現跨平臺頭像同步（如 GitHub、Stack Overflow）。

步驟 1：進入個人資料設置
登錄 npm 官網（https://www.npmjs.com/），點擊右上角 “頭像圖標”（默認顯示首字母），選擇 “Profile Settings”。
步驟 2：設置頭像
1. 本地上傳：在 “Avatar” 區域點擊 “Change Avatar”，選擇本地圖片（推薦尺寸 200x200px，格式 PNG/JPG，大小≤1MB），裁剪后保存。
2. 關聯 Gravatar：若頁面顯示 “Change your Gravatar”，點擊后跳轉至Gravatar 官網，使用與 npm 賬號相同的郵箱登錄，上傳或修改頭像后，npm 會自動同步（同步延遲約 5 分鐘）。
- 注意：Gravatar 是 “全球通用頭像服務”，一次設置可同步至所有支持 Gravatar 的平臺，無需在每個平臺重復上傳。

1.2.4 安全配置

賬號安全配置（可選但推薦）：為避免賬號被盜，建議開啟 “二次驗證（2FA）”：

在 “Profile Settings” 頁面下滑至 “Two-Factor Authentication”，點擊 “Enable 2FA”。
按提示下載 Authenticator 應用（如 Google Authenticator），掃描二維碼綁定賬號，后續登錄或發布包時需輸入應用生成的動態驗證碼。

1.3 初始配置

項目初始化與 package.json 配置：項目初始化的核心是生成package.json文件 —— 它是 npm 包的 “身份說明書”，記錄包名、版本、入口文件等關鍵信息，直接影響包的發布與使用。

1.3.1 初始項目目錄

新建項目文件夾（如websocket-encaps，建議與包名一致），通過終端進入該目錄：

bash

# Windows示例
cd G:\1. My_file🔒\2 FrontEnd\Code\WebSocket
# macOS/Linux示例
cd ~/FrontEnd/Code/WebSocket

執行初始化命令，按提示填寫信息：
bash
```
npm init
```

1.3.2 關鍵字段詳解

package.json 關鍵字段詳解（避坑重點）：npm init過程中需填寫多個字段，部分字段有嚴格規則，錯誤配置會導致發布失敗或用戶無法使用，以下是核心字段的含義與填寫規范：

字段名	含義與作用	填寫規范與注意事項
`name`	包名（npm 上唯一標識，用戶通過該名稱安裝）	1. 不可包含大寫字母（報錯 “Sorry, name can no longer contain capital letters”）； 2. 不可與 npm 現有包重名（發布前需在 npm 官網搜索確認）； 3. 若為私有包，建議加作用域（如`@你的用戶名/websocket-encaps`）；示例：`websocket-encaps`（正確）、`WebSocket-Encaps`（錯誤）。
`version`	版本號（遵循語義化版本規范，影響用戶更新判斷）	1. 格式：`major.minor.patch`（主版本。次版本。補丁版本）； 2. 首次發布建議填`1.0.0`； 3. 不可手動修改后重復發布（需通過`npm version`更新）；示例：修復 Bug 用`1.0.1`，新增功能用`1.1.0`，破壞性變更用`2.0.0`。
`description`	包的功能描述（顯示在 npm 搜索結果與包詳情頁）	簡潔明了，包含核心能力，便于用戶快速理解；示例：“一個支持自動重連、消息封裝的 WebSocket 工具包”。
`main`	包的入口文件（用戶`require`或`import`時加載的文件）	1. 路徑需正確（相對于`package.json`的位置）； 2. 若核心文件為`websocket.js`，直接填`websocket.js`；若在`src`目錄下，填`src/websocket.js`；錯誤示例：填`./websocket.js`（雖能生效，但不符合規范）、填`index.js`（但實際入口是`websocket.js`，導致用戶引入失敗）。
`scripts`	自定義腳本（如測試、構建）	常用腳本：`"test": "node websocket.js"`（執行測試）、`"build": "babel src -d dist"`（構建 ES5 代碼）；注意：若腳本為空，可直接按回車留空，后續可手動修改。
`keywords`	搜索關鍵詞（提升 npm 搜索排名，幫助用戶找到包）	1. 用英文逗號分隔，避免中文（npm 搜索優先識別英文）； 2. 包含核心能力詞，如`["websocket", "autoreconnect", "message-encapsulation", "socket-client"]`；錯誤示例：填`"websocket","websocket-encaps"`（多余引號，會導致關鍵詞帶引號，影響搜索）。
`author`	作者信息（可填姓名、郵箱或 GitHub 鏈接）	格式推薦：`“作者名 <郵箱> (GitHub鏈接)”`，示例：`“NCSmile <ncsmile@example.com> (https://github.com/NCSmile)”`；注意：若填 GitHub 鏈接，需確保鏈接可訪問。
`license`	開源許可證（默認`ISC`，與`MIT`類似，均為寬松協議）	無需修改默認值，若需指定`MIT`，直接輸入`MIT`即可；建議在項目根目錄添加`LICENSE`文件（復制對應許可證文本），增強合規性。
`repository`	代碼倉庫地址（如 GitHub，便于用戶查看源碼、貢獻代碼）	格式：`"repository": { "type": "git", "url": "git+https://github.com/NCSmile/websocket-encaps.git" }`；注意：需先在 GitHub 創建倉庫，再填寫該字段，后續發布后會在 npm 包頁面顯示 “Repository” 鏈接。

1.3.3 手動完善

手動完善 package.json（可選優化）：初始化完成后，可手動編輯package.json，添加以下優化字段：

files：指定發布到 npm 的文件范圍（避免冗余文件被打包），示例：
```
"files": ["websocket.js","README.md","LICENSE"
]
```
作用：排除node_modules、test目錄、日志文件等無需發布的內容，減小包體積。
homepage：包的主頁（如 GitHub 倉庫的 README 地址），示例：
```
"homepage": "https://github.com/NCSmile/websocket-encaps#readme"
```
作用：在 npm 包頁面顯示 “Homepage” 鏈接，方便用戶查看詳細文檔。

二、核心內容

npm 包核心內容開發與多場景適配：完成準備工作后，進入核心開發環節，需編寫高質量代碼、完善文檔，并適配不同使用場景（如原生 JS、Vue2），確保包的可用性與易用性。

2.1 核心功能

核心功能代碼編寫（以 WebSocket 封裝為例）：以本文案例中的 “WebSocket 封裝工具包” 為例，詳細拆解核心代碼的編寫邏輯與注意事項，確保代碼健壯性與可復用性。

2.1.1 核心文件

核心文件結構設計：推薦的項目文件結構（簡潔清晰，避免冗余）：

websocket-encaps/
├── websocket.js       # 核心功能代碼（入口文件）
├── package.json       # 包配置文件
├── README.md          # 使用說明文檔
├── LICENSE            # 開源許可證（可選）
└── .npmignore         # 排除無需發布的文件（可選）

最后兩個文件是可選文件，可手動創建，也可通過命令創建。

2.1.2 封裝代碼

WebSocket 封裝代碼解析：以下是websocket.js的完整代碼，包含連接初始化、自動重連、消息發送 / 接收等核心能力，并標注關鍵邏輯與注意事項：

javascript

/*** WebSocket封裝工具包* 功能：自動重連、消息JSON解析、Token攜帶、狀態監聽* 依賴：js-cookie（用于獲取用戶Token，需用戶項目安裝）*/// 1. 定義全局變量（存儲Socket實例與回調函數）
let socket = null;          // Socket實例
let handleMessage = null;   // 消息接收回調（用戶自定義）
let handleErr = null;       // 錯誤處理回調（用戶自定義）
let reconnectTimer = null;  // 重連定時器（避免頻繁重連）
const RECONNECT_INTERVAL = 3000; // 重連間隔（3秒，可配置）// 2. 引入依賴（需提示用戶安裝js-cookie）
// 注意：若用戶項目未安裝，需在README中說明“npm install js-cookie”
import Cookies from 'js-cookie';
const TokenKey = 'Admin-Token'; // Token的Cookie鍵名（需與用戶項目一致）
const getUserToken = () => Cookies.get(TokenKey) || ''; // 獲取Token（兼容無Token場景）/*** 3. 初始化WebSocket連接* @param {String} url - WebSocket服務器地址（如ws://localhost:8080）* @param {Object} initData - 初始化時發送的參數（如用戶ID、業務類型）* @param {Boolean} autoReconnect - 是否自動重連（默認true）*/
export function initSocket(url, initData = {}, autoReconnect = true) {// 校驗WebSocket支持性（兼容低版本瀏覽器）if (typeof WebSocket === 'undefined') {console.error('WebSocket初始化失敗：當前環境不支持WebSocket');handleErr?.('不支持WebSocket');return;}// 關閉已有連接（避免重復創建）if (socket) {socket.close(1000, '初始化新連接，關閉舊連接');socket = null;}// 4. 創建Socket實例（攜帶Token，支持兩種傳參方式）try {// 方式1：通過協議參數攜帶Token（適用于服務器從協議參數獲取Token）const token = getUserToken();const socketUrl = token ? `${url}?token=${token}` : url;socket = new WebSocket(socketUrl);// 方式2：通過子協議攜帶Token（若服務器從子協議獲取，需替換為以下代碼）// socket = new WebSocket(url, [getUserToken()]);// 5. 監聽Socket狀態// 連接成功socket.onopen = (e) => {console.log('WebSocket連接成功', e);// 清除重連定時器（連接成功后停止重連）if (reconnectTimer) clearInterval(reconnectTimer);// 發送初始化參數（若有）if (Object.keys(initData).length > 0) {socketSend(initData);}};// 接收消息socket.onmessage = (e) => {try {// 解析JSON格式消息（兼容非JSON消息）const data = JSON.parse(e.data);handleMessage?.(data); // 觸發用戶回調} catch (err) {console.warn('WebSocket消息解析失敗（非JSON格式）', e.data);handleMessage?.(e.data); // 直接傳遞原始消息}};// 連接錯誤socket.onerror = (e) => {console.error('WebSocket連接錯誤', e);handleErr?.('連接錯誤，請檢查服務器地址或網絡');// 觸發自動重連（若開啟）if (autoReconnect) startReconnect(url, initData);};// 連接關閉socket.onclose = (e) => {console.log('WebSocket連接關閉', e);// 觸發自動重連（若開啟且關閉碼非正常關閉）if (autoReconnect && e.code !== 1000) {startReconnect(url, initData);}};} catch (err) {console.error('WebSocket創建失敗', err);handleErr?.('創建連接失敗');}
}/*** 6. 自動重連邏輯（避免頻繁重連，增加間隔控制）* @param {String} url - WebSocket服務器地址* @param {Object} initData - 初始化參數*/
function startReconnect(url, initData) {// 清除已有定時器（避免多個定時器同時運行）if (reconnectTimer) clearInterval(reconnectTimer);// 間隔3秒重連（可根據需求調整）reconnectTimer = setInterval(() => {console.log('WebSocket嘗試重連...');initSocket(url, initData);}, RECONNECT_INTERVAL);
}/*** 7. 發送消息（確保連接處于就緒狀態）* @param {Object} data - 發送的消息（需為JSON可序列化格式）*/
export function socketSend(data) {// 檢查Socket狀態：1為連接就緒if (socket?.readyState === 1) {try {socket.send(JSON.stringify(data)); // 序列化后發送} catch (err) {console.error('WebSocket消息發送失敗', err);handleErr?.('消息發送失敗');}} else if (socket?.readyState === 3) {// 狀態3：連接已關閉console.error('WebSocket發送失敗：連接已關閉');handleErr?.('連接已關閉，無法發送消息');} else {// 狀態0：連接正在建立；狀態2：連接正在關閉console.warn('WebSocket發送失敗：連接未就緒', socket?.readyState);handleErr?.('連接未就緒，請稍后再試');}
}/*** 8. 對外暴露的連接函數（簡化用戶使用）* @param {String} url - WebSocket地址* @param {Object} initData - 初始化參數* @param {Function} onMessage - 消息接收回調* @param {Function} onError - 錯誤處理回調* @param {Boolean} autoReconnect - 是否自動重連*/
export function connectSocket(url, initData = {}, onMessage, onError, autoReconnect = true) {// 綁定用戶回調（覆蓋舊回調，避免多個組件共用時沖突）handleMessage = onMessage || null;handleErr = onError || null;// 初始化連接initSocket(url, initData, autoReconnect);
}/*** 9. 關閉WebSocket連接（手動觸發）*/
export function closeSocket() {if (socket) {// 正常關閉（代碼1000，原因“手動關閉”）socket.close(1000, '用戶手動關閉連接');socket = null;}// 清除重連定時器if (reconnectTimer) {clearInterval(reconnectTimer);reconnectTimer = null;}
}// 10. 暴露Socket實例（方便用戶獲取原始狀態，可選）
export function getSocketInstance() {return socket;
}

2.1.2 代碼編寫注意事項

兼容性處理：
- 檢查typeof WebSocket === 'undefined'，兼容不支持 WebSocket 的瀏覽器（如 IE8 及以下）。
- 消息解析時用try-catch包裹JSON.parse，避免非 JSON 格式消息導致代碼崩潰。
資源釋放：
- 關閉連接時清除重連定時器（clearInterval(reconnectTimer)），避免內存泄漏。
- 初始化新連接前關閉舊連接（socket.close()），避免重復創建連接。
依賴說明：
代碼依賴js-cookie，需在 README 中明確告知用戶 “安裝包時需額外安裝js-cookie”（npm install websocket-encaps js-cookie），避免用戶引入時報錯 “Cannot find module 'js-cookie'”。
參數容錯：
對initData、onMessage等參數設置默認值（如initData = {}），避免用戶未傳參導致的undefined錯誤。

2.2 說明文件

README.md 編寫（決定包的易用性）：README.md 是用戶了解包的第一入口，需包含 “安裝方法、使用示例、API 文檔、注意事項” 等核心內容，格式需符合 Markdown 規范，確保在 npm 官網正確渲染。

模板示例

README.md 模板（以 WebSocket 封裝包為例）：markdown

# websocket-encaps一個輕量級、高可用的WebSocket封裝工具包，支持自動重連、消息JSON解析、Token攜帶，適配原生JS、Vue、React等多場景。## 🌟 核心功能
- ? 自動重連：連接斷開后按配置間隔重試，避免手動處理重連邏輯
- ? Token攜帶：支持從Cookie獲取Token，通過URL參數或子協議傳遞給服務器
- ? 消息封裝：自動序列化/反序列化JSON消息，兼容非JSON格式消息
- ? 狀態監聽：暴露連接、消息、錯誤、關閉等回調，便于業務處理
- ? 資源安全：手動關閉連接時自動清除定時器，避免內存泄漏## 📦 安裝
### 1. 安裝核心包與依賴
本包依賴`js-cookie`獲取Token，需同時安裝：
```bash
# npm安裝
npm install websocket-encaps js-cookie --save# yarn安裝（若用戶使用yarn）
yarn add websocket-encaps js-cookie......

2.3 環境要求

Node.js：≥14.x（若用于 Node.js 環境）
瀏覽器：支持 ES6 + 與 WebSocket API（Chrome ≥43、Firefox ≥11、Edge ≥12）
框架：Vue 2/3、React ≥16.x、Angular ≥8.x（均兼容）

2.4?使用示例

場景 1：JavaScript

原生 JavaScript（瀏覽器 / Node.js）

// 1. 引入包
const { connectSocket, socketSend, closeSocket } = require('websocket-encaps');// 2. 初始化連接
const wsUrl = 'ws://localhost:8080/websocket'; // 你的WebSocket服務器地址
connectSocket(wsUrl,{ userId: '123', businessType: 'chat' }, // 初始化時發送的參數(data) => {// 3. 處理收到的消息console.log('收到服務器消息：', data);// 業務邏輯：如彈窗提醒、更新頁面數據if (data.type === 'notification') {alert(`收到通知：${data.content}`);}},(errMsg) => {// 4. 處理錯誤console.error('WebSocket錯誤：', errMsg);alert(`WebSocket錯誤：${errMsg}`);},true // 是否自動重連（默認true）
);// 5. 發送消息（例如點擊按鈕時觸發）
document.getElementById('sendBtn').addEventListener('click', () => {socketSend({type: 'chat',content: 'Hello, WebSocket!',timestamp: new Date().getTime()});
});// 6. 頁面關閉前關閉連接（避免資源泄漏）
window.addEventListener('beforeunload', () => {closeSocket();
});

場景 2：Vue 2

<template><div class="websocket-demo"><button @click="sendChatMessage">發送聊天消息</button><div class="message-list"><div v-for="(msg, idx) in messageList" :key="idx">{{ new Date(msg.timestamp).toLocaleString() }}：{{ msg.content }}</div></div></div>
</template><script>
// 1. 引入包
import { connectSocket, socketSend, closeSocket } from 'websocket-encaps';
import Cookies from 'js-cookie'; // 若需自定義Token獲取邏輯，可引入后重寫export default {name: 'WebSocketDemo',data() {return {messageList: [], // 存儲收到的消息wsUrl: 'ws://localhost:8080/websocket' // 服務器地址};},created() {// 2. 組件創建時初始化連接this.initWebSocket();},beforeDestroy() {// 3. 組件銷毀前關閉連接（關鍵：避免內存泄漏）closeSocket();},methods: {// 初始化WebSocketinitWebSocket() {connectSocket(this.wsUrl,{ userId: Cookies.get('userId'), businessType: 'chat' }, // 初始化參數（攜帶用戶ID）this.handleReceivedMessage, // 消息回調this.handleSocketError,    // 錯誤回調true                       // 自動重連);},// 處理收到的消息handleReceivedMessage(data) {console.log('Vue2收到消息：', data);// 將消息添加到列表（響應式更新視圖）this.messageList.push(data);// 業務邏輯：如使用Element UI的消息提示if (this.$message && data.type === 'notification') {this.$message.success(`通知：${data.content}`);}},// 處理錯誤handleSocketError(errMsg) {console.error('Vue2 WebSocket錯誤：', errMsg);this.$message?.error(`WebSocket錯誤：${errMsg}`);},// 發送聊天消息sendChatMessage() {const message = {type: 'chat',content: `Vue2發送的消息：${new Date().toLocaleString()}`,timestamp: new Date().getTime()};socketSend(message);}}
};
</script><style scoped>
.websocket-demo {padding: 20px;
}
button {padding: 8px 16px;margin-bottom: 15px;cursor: pointer;background: #409eff;color: #fff;border: none;border-radius: 4px;
}
.message-list {border: 1px solid #e6e6e6;padding: 10px;height: 300px;overflow-y: auto;
}
.message-list div {margin-bottom: 8px;line-height: 1.5;
}
</style>

場景 3：Vue 3

Vue 3（Composition API）

<template><div class="websocket-demo"><button @click="sendChatMessage">發送消息</button><div v-for="(msg, idx) in messageList" :key="idx">{{ msg.timestamp }}：{{ msg.content }}</div></div>
</template><script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { connectSocket, socketSend, closeSocket } from 'websocket-encaps';
import Cookies from 'js-cookie';// 響應式變量：存儲消息列表
const messageList = ref([]);
const wsUrl = 'ws://localhost:8080/websocket';// 初始化連接（組件掛載時）
onMounted(() => {connectSocket(wsUrl,{ userId: Cookies.get('userId') },handleReceivedMessage,handleSocketError);
});// 關閉連接（組件卸載時）
onUnmounted(() => {closeSocket();
});// 處理收到的消息
const handleReceivedMessage = (data) => {messageList.value.push(data);console.log('Vue3收到消息：', data);
};// 處理錯誤
const handleSocketError = (errMsg) => {console.error('Vue3 WebSocket錯誤：', errMsg);// 若使用Element Plus，可調用ElMessage// ElMessage.error(`WebSocket錯誤：${errMsg}`);
};// 發送消息
const sendChatMessage = () => {socketSend({type: 'chat',content: `Vue3消息：${new Date().toLocaleString()}`,timestamp: new Date().getTime()});
};
</script>

2.5?文檔說明

2.5.1?核心函數

函數名	作用	參數說明
`connectSocket`	初始化 WebSocket 連接	-?`url`：必填，WebSocket 服務器地址（如`ws://localhost:8080`）； -?`initData`：可選，初始化時發送的參數（默認`{}`）； -?`onMessage`：可選，消息接收回調（參數為解析后的消息）； -?`onError`：可選，錯誤處理回調（參數為錯誤描述）； -?`autoReconnect`：可選，是否自動重連（默認`true`）。
`socketSend`	發送消息到服務器	-?`data`：必填，發送的消息（需為 JSON 可序列化格式，如對象、數組）。
`closeSocket`	手動關閉 WebSocket 連接	無參數。
`getSocketInstance`	獲取原始 WebSocket 實例	無參數，返回`WebSocket`實例（可用于自定義狀態監聽）。

2.5.2?回調函數

onMessage(data)：收到服務器消息時觸發，data為解析后的 JSON 對象（若消息非 JSON 格式，為原始字符串）。
onError(errMsg)：連接錯誤、發送失敗等場景觸發，errMsg為錯誤描述字符串（如 “連接已關閉，無法發送消息”）。

2.5.3?狀態說明

WebSocket 狀態碼說明

狀態碼	含義	場景說明
0	CONNECTING	連接正在建立，此時調用`socketSend`會提示 “連接未就緒”。
1	OPEN	連接已就緒，可正常發送 / 接收消息。
2	CLOSING	連接正在關閉，此時發送消息會失敗。
3	CLOSED	連接已關閉，需重新調用`connectSocket`初始化連接（自動重連會自動處理）。

2.6 注意事項

Token 配置：本包默認從 Cookie 讀取 Admin-Token。若 Token 鍵名不同，可修改 websocket.js 中的 TokenKey 常量，或在 getUserToken 函數中自定義獲取邏輯。
Token 傳遞方式：WebSocket 不支持自定義請求頭，若服務端需通過 Header 驗證 Token，建議改用 URL 參數 或 子協議 攜帶，并在 initSocket 函數中配置對應方式。
跨域處理：瀏覽器中 WebSocket 需服務器在握手階段配置跨域策略（如 Access-Control-Allow-Origin）。推薦使用 wss:// 協議，以降低跨域限制風險。
大文件傳輸：傳輸大文件時應分片發送，避免單條消息過大導致斷連。建議改用二進制格式（Blob/ArrayBuffer），并在 socketSend 中取消 JSON.stringify。
多組件與環境適配：多組件共用時，建議將 connectSocket 和 closeSocket 封裝至全局狀態管理（如 Vuex/Pinia）。Node.js 環境需安裝 ws 包，并通過 global.WebSocket = require('ws') 兼容。

三、文件更新

包文件的更新：當我們已經發布了一個 npm 包，并且在后續開發過程中需要修改其中的代碼或修復 bug 時，就需要對包文件進行更新和重新發布。更新流程相對簡單，但一定要嚴格按照步驟來操作，以確保版本管理清晰，并避免對使用你包的用戶造成影響。

以下是標準的 npm 包更新流程：

更新步驟：

更新 npm 包主要分為三個步驟：更新版本號 → 打包檢查 → 發布新版本。
完整流程如下：

第一步：更新版本號

首先對已有的代碼文件進行修改，例如在 myLib.js 中增加新的方法或修復錯誤。
修改完成后，務必進行本地測試，確保更新后的代碼可以正常運行。

然后使用以下命令快速更新版本號：

npm version patch

版本號說明（語義化版本 SemVer）：

patch：修復 bug 或小改動，例如 1.0.0 → 1.0.1

minor：新增功能且向下兼容，例如 1.0.0 → 1.1.0

major：存在重大不兼容更新，例如 1.0.0 → 2.0.0

執行 npm version patch 后，npm 會自動完成以下操作：

更新 package.json 中的版本號。
創建一個對應版本的 Git 提交和標簽（如果項目在 Git 管理中）。

第二步：打包檢查

在發布之前，可以先打包生成一個本地 .tgz 文件，檢查即將發布的內容：

npm pack

執行后會生成類似 my-npm-package-1.0.1.tgz 的壓縮包文件。
可以手動解壓該文件，確認包含的代碼和文件是否正確，避免發布冗余或錯誤文件。

建議：
使用 .npmignore 文件來控制哪些文件需要被排除在發布包之外，例如測試代碼、日志文件等。

第三步：發布新版本

確認打包無誤后，執行以下命令將新版本發布到 npm：

npm publish

注意事項：

如果是首次發布作用域包（scoped package），需要加上 --access public：

npm publish --access public

--access public?的核心作用是：強制將 scope 包標記為 “公共包”，允許所有人訪問和安裝。

免費 npm 用戶可以發布?公開的 scope 包（必須加?--access public），但不能發布私有 scope 包；
付費用戶（如 npm Pro、Teams）可以發布私有 scope 包，也可以發布公開 scope 包（加?--access public）；
無論是普通包還是公開的 scope 包，安裝和使用方式完全一致，用戶無需額外學習成本。

具體區別：

普通包以package-name命名，需全局唯一，默認公開，適合通用工具；scope 包以**@owner/package-name命名，僅需在@owner**下唯一，默認私有（免費用戶需加 --access public 發布為公開），更適合避免命名沖突、明確歸屬（個人/組織）或需要私有包的場景，兩者使用方式一致。

第四步：驗證更新結果

發布完成后，驗證更新是否成功：

查看最新版本信息：

npm view websocket-encaps

//或者

npm info
在其他項目中安裝并測試：

npm install websocket-encaps
驗證代碼是否運行正常

npm view?和?npm info?是完全等價的命令，含義和功能一模一樣，都是用于查詢 npm 倉庫中某個包的詳細信息（如版本、作者、依賴、發布時間、描述等）。

小結：更新 npm 包的核心流程可以概括為三步：

更新版本號 → npm version patch

打包檢查 → npm pack

發布新版本 → npm publish

只要嚴格按照這三步執行，就能保證 npm 包的版本管理清晰、穩定，并方便用戶快速升級到最新版本。

四、命令總結

下面是 npm 包發布與更新的命令總結，按流程排序，每條命令都附帶簡短注釋，涵蓋了首次發布和后續更新兩種場景：

首次發布：

# 1. 初始化 package.json 文件
npm init -y        # 自動生成 package.json# 2. 登錄 npm 賬號
npm login          # 使用 npm 賬號登錄，輸入用戶名、密碼、郵箱# 3. 檢查即將發布的內容
npm pack           # 生成本地 tar 包，檢查發布文件是否正確# 4. 發布包
npm publish --access public  # 首次發布作用域包需要 --access public

包的更新：

# 1. 修改代碼后，更新版本號
npm version patch   # 小修復，例如 1.0.0 -> 1.0.1
# 也可用 npm version minor / major# 2. 檢查發布內容
npm pack            # 打包檢查，確保文件正確# 3. 發布新版本
npm publish         # 發布更新后的版本

驗證結果：

npm view 包名         # 查看包的最新版本信息
npm install 包名      # 安裝最新版本測試

流程總結：

首次發布：初始化 → 登錄 → 打包檢查 → 首次發布
文件更新：修改代碼 → 更新版本號 → 打包檢查 → 發布新版本 → 驗證結果

整體排序（包括同步到GitHub倉庫）：

首次發布（按流程）：

npm config get registry
查看當前 npm 鏡像源，確保發布時使用官方源（https://registry.npmjs.org/）

npm config set registry https://registry.npmjs.org/
若當前不是官方源，切換到官方源（避免發布失敗）

npm login
登錄 npm 賬號（輸入用戶名、密碼、郵箱驗證碼，確保賬號已驗證郵箱）

npm init
初始化項目生成package.json（首次發布前執行，配置包名、入口等信息）

npm version 1.0.0
首次發布時手動設置初始版本（或直接在package.json中配置）

npm pack
打包生成.tgz文件，預覽即將發布的內容（檢查核心文件是否包含，無冗余）

npm publish
首次發布包到 npm 官網（成功后終端顯示+ 包名@版本號）

git add . && git commit -m "feat: 初始版本發布"
提交代碼到本地 Git 倉庫（與 npm 包內容同步）

git tag v1.0.0 && git push origin v1.0.0
打版本標簽并推送到 GitHub（便于版本回溯和多平臺同步）

更新文件（按流程）：

npm version patch
修復 Bug 時更新補丁版本（如 1.0.0 → 1.0.1，語義化版本：小改動）

npm version minor
新增功能時更新次版本（如 1.0.1 → 1.1.0，語義化版本：兼容改動）

npm version major
破壞性變更時更新主版本（如 1.1.0 → 2.0.0，語義化版本：不兼容改動）

npm pack
打包預覽更新內容（確認修改已生效，無錯誤文件）

npm publish
發布更新后的版本到 npm（覆蓋舊版本，用戶可通過npm update獲取）

git push origin main && git push origin --tags
推送更新后的代碼和版本標簽到 GitHub（保持 npm 與 GitHub 代碼同步）

黃色背景部分，博主認為最為重要，具體情況，按照實際需求操作。

五、本文總結

本文總結了 npm 包從 0 到 1 的開發、發布、更新全流程，包括發布前切換 npm 官方源、開發更新時的語義化版本管理、與 GitHub 的多平臺同步；同時涵蓋了包名重復、版本沖突等高頻問題的規避要點，幫助我們高效完成 npm 包的全生命周期維護。

通過本文，我們完整梳理了 npm 包發布與更新的全流程，從初次發布到后續維護，都給出了詳細的步驟與注意事項：

初次發布
- 使用 npm init 初始化項目。
- npm login 登錄 npm 賬號。
- npm pack 檢查發布文件。
- npm publish --access public 首次發布包。
后續更新
- 修改代碼后，通過 npm version patch 更新版本號，保持語義化版本管理。
- 使用 npm pack 確認打包內容正確。
- npm publish 發布新版本。
驗證與維護
- 通過 npm view 包名 查看版本信息。
- 在項目中使用 npm install 包名 測試最新版本。
- 持續優化并維護文檔和更新日志，保證包的長期可用性。