NuGet01-安装及使用
零、文章目录
NuGet01-安装及使用
1、介绍
(1)介绍
- NuGet是.NET的包管理器。
- NuGet客户端工具提供了生成和消费包的能力。
- NuGet Gallery是所有包作者和消费者使用的中央包存储库。
(2)官方主页
- 官网主页:https://www.nuget.org/,提供包搜索、账号管理及文档入口。
- 官方文档:https://docs.microsoft.com/nuget/,包含包管理、发布及私有仓库搭建的详细说明。
(3)核心功能
- 依赖管理
- 自动处理包的安装、更新和依赖关系,避免手动管理 DLL 文件。
- 支持版本控制,允许指定兼容的包版本范围(如
1.0.0
到2.0.0
)。
- 包分发与共享
- 包以
.nupkg
格式分发,包含编译后的代码(DLL)、元数据和依赖清单。 - 支持公共仓库(如 nuget.org)和私有仓库(如 Azure DevOps 或本地服务器)。
- 包以
- 跨框架兼容
- 通过
.NET Standard
实现跨框架兼容(如 .NET Core、.NET Framework)。 - 支持多目标构建(同一包适配多个框架版本)。
- 通过
(4)使用场景
- 安装包
- Visual Studio:右键项目 → 管理 NuGet 包 → 搜索并安装(如
Newtonsoft.Json
)。 - 命令行:
Install-Package Newtonsoft.Json
(控制台)或dotnet add package Newtonsoft.Json
(CLI)。
- Visual Studio:右键项目 → 管理 NuGet 包 → 搜索并安装(如
- 创建与发布包
- 创建类库项目 → 生成
.nupkg
文件(通过nuget pack
或dotnet pack
)。 - 发布到 nuget.org 需 API Key,命令行示例:
dotnet nuget push MyPackage.nupkg --api-key xxxx
。
- 创建类库项目 → 生成
- 依赖解析
- 自动解析包依赖树。例如,安装包 A 时,NuGet 会自动下载其依赖的包 B 和包 C。
2、安装配置
(1)安装
- Visual Studio集成工具
- 适用于Windows开发环境,通过VS扩展管理器安装:
工具 > 扩展和更新 > 联机库 > 搜索并安装 NuGet Package Manager
- 安装后可在菜单
工具 > NuGet包管理器
中使用图形化界面或控制台。
- 适用于Windows开发环境,通过VS扩展管理器安装:
- dotnet CLI(推荐跨平台使用)
- 随.NET SDK自动安装,支持.NET Core/.NET 5+项目:
# 安装包示例
dotnet add package Newtonsoft.Json
- 验证安装:`dotnet --version` 输出版本即成功。
- nuget.exe (传统.NET Framework项目)
- 独立下载地址:https://www.nuget.org/downloads
- 配置环境变量:将
nuget.exe
所在目录添加到系统PATH。
(2)官方仓库源
- 新版仓库(V3 API)
- 地址:
https://api.nuget.org/v3/index.json
- 特点:微软官方维护的公共仓库,包含超过 10 万个开源库,支持新版协议,性能更优且依赖解析更高效。推荐优先使用此地址。
- 地址:
- 旧版仓库(V2 API)
- 地址:
https://www.nuget.org/api/v2/
- 特点:旧版协议,兼容部分遗留工具链,但可能存在性能或兼容性问题,建议仅在特殊场景下使用。
- 地址:
(3)国内镜像源
- 清华大学镜像源
- 地址:
https://mirrors.tuna.tsinghua.edu.cn/nuget/
- 特点:国内访问速度快,定期同步官方仓库,适合国内开发者使用。
- 地址:
- 阿里云镜像源
- 地址:
https://nuget.cdn.azure.cn/v3/index.json
- 特点:微软 Azure 提供的镜像源,稳定性高。
- 地址:
(4)配置仓库源
- Visual Studio:在“工具 → NuGet 包管理器 → 包管理器设置”添加源地址。
- 安装包时可以指定私有源:
nuget install MyPackage -Source "http://your-nuget-server/v3/index.json"
(5)注意事项
- 优先使用 V3 API:新版 V3 API 性能更好,且支持更多特性(如依赖解析优化),旧版 V2 地址可能因兼容性问题导致连接失败。
- 镜像源同步延迟:国内镜像源可能存在数小时至一天的同步延迟,紧急需求建议直接使用官方源。
3、配置文件
- 配置文件用于存储设置(如包源、缓存路径)。
(1)默认路径
- 用户级配置
- Windows:
C:\Users\{用户名}\AppData\Roaming\NuGet\NuGet.Config
- Mac/Linux:
~/.nuget/NuGet/NuGet.Config
- Windows:
- 项目级配置
- 解决方案或项目根目录:
{项目路径}/nuget.config
- 解决方案或项目根目录:
- 全局/机器级配置
- Windows:
C:\Program Files (x86)\NuGet\Config\NuGet.Config
- Windows:
(2)自定义路径
- 通过环境变量:设置
NUGET_PACKAGES
可修改全局包缓存路径。
# Windows
setx NUGET_PACKAGES "D:\CustomNuGetPackages"
# Linux/Mac
export NUGET_PACKAGES="/opt/CustomNuGetPackages"
- 通过配置文件:在
nuget.config
中添加以下配置,自定义全局包路径:
<config><add key="globalPackagesFolder" value="D:\NuGetPackages" />
</config>
(3)查看配置信息
- 命令行查看信息
# 查看所有 NuGet 相关路径(包括缓存、全局包路径)
dotnet nuget locals all --list
- Visual Studio:通过
工具 → NuGet 包管理器 → 包管理器设置
查看当前加载的配置文件列表。
(4)优先级规则(高到低)
- 项目级
nuget.config
- 用户级
NuGet.Config
- 全局/机器级
NuGet.Config
- 环境变量(如
NUGET_PACKAGES
)。
(5)注意事项
- 多层级配置合并:子目录的
nuget.config
会继承并覆盖父目录的配置。 - 默认路径不存在时:若用户级或项目级
nuget.config
文件缺失,NuGet 会自动使用内置默认值。
4、Visual Studio集成工具操作
(1)安装包
- 图形界面
- 打开 Visual Studio 项目。
- 右键点击项目,选择“管理 NuGet 包”。
- 也可以对整个解决方案配置,右键解决方案。
- 在搜索框中输入需要的包名,找到包后点击“安装”。
- 控制台
- 打开 Visual Studio。
- 导航到“工具” > “NuGet 包管理器” > “包管理器控制台”。
- 使用命令
Install-Package “包名”
来安装包。
(2)卸载包
- 图形界面
- 在解决方案资源管理器中,右键点击项目,选择“管理 NuGet 包”。
- 选择“已安装”选项卡,找到需要卸载的包,点击“卸载”。
- 控制台
- 使用命令
Uninstall-Package 包名
来卸载包。
- 使用命令
(3)更新包
- 图形界面
- 右键点击项目,选择“管理 NuGet 包”。
- 选择“更新”选项卡,查看可用更新的包。
- 选择需要更新的包,选择所需版本后点击“更新”。
- 控制台
- 使用命令
Update-Package 包名
来更新包。
- 使用命令
(4)缓存清理
- Visual Studio:在“工具 → NuGet 包管理器 → 包管理器设置”。
- 缓存异常可能导致安装失败,建议定期清理。
(5)包恢复
- 选中解决方案,还原 Nuget 包
(6)离线安装包
- 如果需要在没有网络连接的环境中安装 NuGet 包,可以下载
.nupkg
文件到本地,然后在 Visual Studio 的 NuGet 包管理器控制台中指定本地路径进行安装。
(7)项目类型差异
- .NET Framework:依赖
packages.config
文件。 - .NET Core:依赖
.csproj
中的<PackageReference>
节点。
5、NuGet命令行操作
(1)安装包
# 默认安装最新版本(当前项目)
nuget install Newtonsoft.Json # 指定版本和项目(PackageReference格式)
dotnet add package Newtonsoft.Json -v 13.0.1
📌 注意:
nuget install
不修改项目文件,需手动添加引用;dotnet add
自动更新项目文件[12]。
(2)更新包
# 更新解决方案所有包(packages.config格式)
nuget update MySolution.sln # 更新指定项目包(PackageReference格式)
dotnet update MyProject.csproj
(3)卸载包
# 卸载指定包
dotnet remove package Newtonsoft.Json
(4)缓存清理
- 缓存异常可能导致安装失败,建议定期清理。
# 清除全局缓存
nuget locals global-packages -clear # 清除临时缓存
nuget locals temp -clear
(5)包恢复
# 恢复解决方案所有包
nuget restore MySolution.sln # 或使用dotnet CLI
dotnet restore
(6)重新安装与修复依赖
- 适用于:包更新后项目损坏、项目重定向后引用失效等场景。
# 强制重新安装所有包(解决引用损坏)
Update-Package -Reinstall -ProjectName MyProject # 重新安装指定包
Update-Package Newtonsoft.Json -Reinstall
(7)常见问题处理
问题场景 | 解决方案 |
---|---|
依赖冲突 | 使用 -DependencyVersion HighestMinor 指定版本策略 |
离线安装本地包 | 添加本地文件夹为源:nuget sources Add -Name "Local" -Source "D:\Packages" |
命令不识别 | 检查环境变量:nuget.exe 目录需加入系统PATH |
包版本锁定 | 在packages.config 中添加 allowedVersions="[1.0,2.0)" 限制升级范围 |
(8)最佳实践建议
- 项目类型适配
.NET Framework
(旧项目):优先用nuget.exe
+packages.config
.NET Core+
(新项目):使用dotnet CLI
+<PackageReference>
- 自动化集成:在CI/CD流水线中加入
nuget restore
和dotnet publish
命令,确保环境一致性。