NuGet Package是什麼？與npm有什麼不同？完整使用指南
更新日期：2025 年 5 月 25 日
本文目錄
在 .NET 開發的世界中，當您需要在專案中使用第三方程式庫或工具時，NuGet Package 就是您最重要的夥伴。NuGet 不僅是 Microsoft .NET 生態系統的官方套件管理工具，更是現代 .NET 開發不可或缺的基礎建設。本文將深入探討 NuGet Package 的核心概念、與 npm 的差異比較，以及完整的使用指南，讓您能夠充分掌握這個強大的套件管理系統。
NuGet Package 基本概念
NuGet（讀音為「New-Get」）是由 Microsoft 開發的套件管理系統，專門為 .NET 平台設計。它允許開發者輕鬆地分享、發布和使用程式碼庫，大幅簡化了 .NET 專案中的依賴管理工作。
NuGet 的核心組成
- NuGet Package：包含程式碼、資源檔案和元資料的壓縮檔案（.nupkg）
- NuGet Gallery：官方的套件存放庫（nuget.org）
- Package Manager：內建於 Visual Studio 的管理工具
- NuGet CLI：命令列介面工具
套件的基本結構
MyPackage.1.0.0.nupkg ├── lib/ │ ├── net462/ │ │ └── MyLibrary.dll │ └── netstandard2.0/ │ └── MyLibrary.dll ├── content/ │ └── readme.txt ├── tools/ │ └── install.ps1 └── MyPackage.nuspec
💡 簡單比喻
想像 NuGet Package 就像是樂高積木包裝盒。每個盒子（套件）裡面包含了特定功能的積木（程式碼），並附有組裝說明書（文件）。開發者可以選擇需要的積木包，然後組合成完整的作品（應用程式）。
NuGet vs npm 詳細比較
雖然 NuGet 和 npm 都是套件管理系統，但它們服務於不同的開發生態系統，在設計理念和使用方式上有顯著差異：
基本差異對照
| 比較項目 | NuGet | npm |
|---|---|---|
| 目標平台 | .NET Framework, .NET Core, .NET 5+ | Node.js, JavaScript 生態系統 |
| 主要語言 | C#, VB.NET, F# | JavaScript, TypeScript |
| 安裝位置 | 全域或專案層級 | node_modules 資料夾 |
| 設定檔案 | packages.config 或 PackageReference | package.json |
| 版本管理 | 語意化版本控制 | 語意化版本控制 + 範圍語法 |
使用場景比較
🔷 NuGet 適用場景
- 企業級 .NET 應用程式開發
- 桌面應用程式（WPF, WinForms）
- Web API 和 ASP.NET 專案
- 雲端服務和微服務架構
- 遊戲開發（Unity）
🔶 npm 適用場景
- 前端網頁開發
- Node.js 後端服務
- 單頁應用程式（SPA）
- 行動應用程式（React Native）
- 開發工具和建置系統
NuGet 安裝與設定
現代的 .NET 開發環境中，NuGet 通常已經預先安裝並整合在開發工具中。以下介紹不同環境下的安裝和設定方式：
Visual Studio 整合
Visual Studio 2012 以後的版本都內建了 NuGet Package Manager，提供圖形化介面：
- Package Manager UI：右鍵專案 → 管理 NuGet 套件
- Package Manager Console：工具 → NuGet 套件管理員 → 套件管理員主控台
- Solution Explorer：直接在方案總管中管理相依性
命令列工具安裝
安裝 NuGet CLI：
# Windows - 使用 Chocolatey
choco install nuget.commandline
# macOS - 使用 Homebrew
brew install nuget
# 或直接下載執行檔
# 從 https://www.nuget.org/downloads 下載 nuget.exe驗證安裝：
nuget --version.NET CLI 整合
現代 .NET 專案推薦使用 .NET CLI 進行套件管理：
# 列出已安裝的套件
dotnet list package
# 新增套件
dotnet add package PackageName
# 移除套件
dotnet remove package PackageName
# 還原套件
dotnet restoreNuGet 實際使用教學
掌握 NuGet 的基本操作是 .NET 開發的必備技能。以下透過實際範例來學習各種常用操作：
搜尋和安裝套件
1. 使用 Visual Studio GUI
右鍵點擊專案 → 選擇「管理 NuGet 套件」
在「瀏覽」標籤中搜尋套件名稱
選擇版本並點擊「安裝」
2. 使用命令列
# 搜尋套件
nuget search Newtonsoft.Json
# 安裝最新版本
dotnet add package Newtonsoft.Json
# 安裝指定版本
dotnet add package Newtonsoft.Json --version 13.0.3套件版本管理
版本號語法說明
| 語法 | 說明 | 範例 |
|---|---|---|
| 1.0 | 精確版本 | 只接受 1.0 |
| [1.0,2.0 | 版本範圍 | 1.0 ≤ 版本 2.0 |
| ,1.0] | 最大版本 | 版本 ≤ 1.0 |
專案檔案設定
現代 .NET 專案格式（SDK-style）
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="6.0.0" />
</ItemGroup>
</Project>舊版專案格式（packages.config）
<?xml version="1.0" encoding="utf-8"?>
<packages>
<package id="Newtonsoft.Json" version="13.0.3" targetFramework="net462" />
<package id="EntityFramework" version="6.4.4" targetFramework="net462" />
</packages>套件發布與管理
除了使用他人的套件，您也可以將自己的程式碼打包發布，與其他開發者分享。以下介紹套件建立和發布的完整流程：
建立 NuGet 套件
步驟 1：準備專案
# 建立類別庫專案
dotnet new classlib -n MyAwesomeLibrary
cd MyAwesomeLibrary步驟 2：設定專案屬性
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.0</TargetFramework>
<PackageId>MyAwesome.Library</PackageId>
<Version>1.0.0</Version>
<Authors>Your Name</Authors>
<Description>一個超棒的工具庫</Description>
<PackageTags>utility;helper;awesome</PackageTags>
<PackageProjectUrl>https://github.com/yourname/library</PackageProjectUrl>
<RepositoryUrl>https://github.com/yourname/library</RepositoryUrl>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>
</Project>步驟 3：建置套件
# 建置並產生 NuGet 套件
dotnet pack --configuration Release發布到 NuGet Gallery
註冊 NuGet.org 帳號
前往 https://www.nuget.org 建立帳號
取得 API 金鑰
在帳號設定中產生新的 API 金鑰
發布套件
dotnet nuget push bin/Release/MyAwesome.Library.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json常見問題與最佳實務
在使用 NuGet 的過程中，開發者經常會遇到一些共通的問題。以下整理了最常見的問題和解決方案，以及一些最佳實務建議：
常見問題解決
❌ 套件版本衝突
問題：多個套件依賴不同版本的同一個函式庫
解決方案：
# 查看套件依賴關係
dotnet list package --include-transitive
# 更新到相容版本
dotnet add package ConflictedPackage --version 2.0.0⚠️ 套件還原失敗
問題：還原過程中出現錯誤，可能是網路問題、來源設定錯誤或套件不存在。
解決方案：
- 確認
nuget.config檔案中來源是否正確。 - 使用
dotnet restore --interactive以處理權限相關問題。 - 檢查網路連線，必要時切換到可用的 NuGet 鏡像站。
- 手動刪除
obj與bin資料夾後重新還原。
⚠️ 無法找到套件版本
問題：指定的套件版本不存在於來源中。
解決方案：
- 確認版本號是否拼寫正確。
- 使用
dotnet add package PackageName --version *試圖抓取可用的最新版本。 - 檢查 NuGet.org 或其他來源是否支援該版本。
ℹ️ 還原速度緩慢
問題：套件還原過程需要很長時間。
解決方案：
- 使用近距離或公司內部的 NuGet Proxy Server。
- 在 CI/CD pipeline 中加上快取策略，避免每次重複還原。
- 確保使用 SSD 或較快磁碟以減少磁碟瓶頸。
✅ 最佳實務建議
- 定期執行
dotnet list package --outdated以掌握依賴更新情況。 - 集中管理
Directory.Packages.props檔案以控制套件版本。 - 避免專案中出現過多不同版本的相同套件。
- 搭配 CI 工具進行套件還原測試，確保專案在乾淨環境中可成功還原。
💡 無法新增套件
問題：執行 dotnet add package 時出現錯誤，提示找不到或有多個專案檔。
解決方案：這個指令必須在含有 .csproj 的專案目錄中執行。如果你在 solution 根目錄或錯誤的位置執行，請使用以下方法：
# 切換到專案目錄
cd MyProject
# 或指定專案檔位置
dotnet add ./MyProject/MyProject.csproj package Newtonsoft.Json套件管理與版本控制
📦 NuGet 是否有像 package.json 的檔案？
不像 npm 使用 package.json 管理套件，.NET 專案會將套件資訊直接寫在 .csproj 專案檔內。每個 <PackageReference> 標籤就代表一個依賴套件。
當你將專案上傳到 GitHub，其他開發者在 clone 專案後，只需執行：
dotnet restore就能根據 .csproj 自動還原所有 NuGet 套件，相當於 npm install 的行為。
若需新增套件，可使用：
dotnet add package 套件名稱這會自動將套件資訊寫入 .csproj，無須手動編輯，也不會產生額外的 package.json 檔案。
🔄 NuGet 跟 npm 的對應關係
| 功能/檔案 | npm / Node.js | NuGet / .NET |
|---|---|---|
| 套件資訊定義檔 | package.json | .csproj（專案檔） |
| 套件鎖定檔（精準版本） | package-lock.json / yarn.lock | packages.lock.json（可選） |
| 安裝指令 | npm install | dotnet restore |
| 安裝單一套件 | npm install lodash | dotnet add package Newtonsoft.Json |
📁 NuGet 套件會下載到哪裡？
和 npm 會將套件放入每個專案的 node_modules 不同，NuGet 會將下載的套件存放在本機的 global cache（例如 Windows 上預設在 %userprofile%\.nuget\packages），並由專案透過路徑參照使用。
這代表同一套件若在多個專案中使用，NuGet 不需要重複下載，每個專案會共用本機快取的版本，節省空間與時間。
但要注意的是：如果不同專案需要的是不同版本的同一套件，NuGet 仍會保留各版本的快取，每個專案依據自身需求選用對應版本。
❓ 多個專案共用套件，是否不用重複記錄依賴？
雖然 NuGet 會將套件下載到本機的 global cache，讓不同專案可共用同一份套件，避免重複下載浪費空間與時間，
但每個專案的 .csproj 檔案中，仍然必須「明確記錄該專案需要使用的套件與版本」，透過 dotnet add package 指令或手動編輯專案檔達成。
換句話說，若你在新專案 B 沒有執行 dotnet add package Newtonsoft.Json，即使你的電腦已經有此套件的 global cache，B 專案的 .csproj 仍不會記錄此依賴，別人 clone B 專案後也不會還原此套件，專案會編譯失敗。
因此，每個專案都要自行宣告所需的套件，才能確保專案可正確還原與運行。
NuGet 雖然強大，但在實際開發中也可能遇到各種錯綜複雜的情況。掌握常見問題的解法並遵循最佳實務，不僅能減少除錯時間，也能提升專案穩定性與維護效率。建議團隊內部建立一致的套件管理流程，定期檢查與更新依賴，才能讓開發更順利、更安心。