1. 从 .NET Framework 到现代 .NET构建与发布到底“革新”在哪写这篇系列的第一篇之前我先说个场景。如果你平时还在 Visual Studio 里右键项目、点击“发布”然后选择文件夹、FTP 或者导入发布配置文件把一堆 DLL 拷到服务器 IIS 上那我建议你先把这套操作暂时放一边。不是说这种方式不能用而是从 .NET Core 出现到 .NET 5 统一再到现在的 .NET 8/9/10 这一整条线走下来整个 .NET 的构建和发布方式已经换了一代打法。不只是命令行工具替代了鼠标点选而是底层项目格式、依赖管理、运行时打包、部署目标、CI/CD 集成全链路都变了。这个系列一我先讲整体认知和核心变化把“为什么说再次革新”这件事拆清楚。后续再深入讲单文件发布、AOT 裁剪、Docker 镜像构建、GitLab CI/CD 自动化这些具体落地场景。这一篇的核心关键词就三个.NET、构建、发布但背后的逻辑线很长。1.1 旧时代的构建发布csproj 加 Visual Studio 发布向导很多人对 .NET 构建的认知停留在 .NET Framework 时代。那时候一个项目就是一个完整的.csprojXML 文件里面密密麻麻列着每一个Compile Include... /和Content Include...。新加一个文件如果忘了修改 csproj编译结果里就没有它。这种显式列举的方式在小型项目里还能忍受项目一旦大起来csproj 冲突、文件遗漏、引用路径写死都是家常便饭。发布就更令人头疼。常见操作是在 Visual Studio 里右键项目 - “发布”选一个目标位置比如文件系统、IIS、FTP 或者 Web Deploy。这个向导确实很友好但它本质上是把 MSBuild 的发布目标包了一层。你很难在命令行里复现同一条发布过程更别说塞到自动化流水线里。发布结果也是一堆紧耦合的 DLL运行时必须装对应版本的 .NET FrameworkWeb 项目还得管应用程序池、集成管道这些 IIS 概念换一台服务器就重新踩一遍配置的坑。我自己的体感是旧模式最大的问题不是“能不能用”而是“不可复现”。同一个解决方案在 A 机器上发布出来的东西和在 B 机器上发布出来的东西经常因为 Visual Studio 版本、NuGet 包缓存、本机安装的 SDK 版本不同而出现差异。这种不确定性在团队协作、CI/CD、多环境部署的场景下是非常痛苦的。1.2 SDK-style 项目文件几百行 csproj 变成几十行革新是从项目文件格式开始的。.NET Core 推出时引入了 SDK-style 项目也就是 csproj 顶部那个Project SdkMicrosoft.NET.Sdk。它的核心理念是“约定大于配置”。默认情况下项目目录下的所有.cs文件都自动纳入编译所有.resx、.json等资源文件也按照默认规则处理不需要再手写 Include。新增文件、重命名文件、删除文件只要用 IDE 或者文件系统操作项目文件本身不需要维护。这对构建体验的提升是颠覆性的。以前因为某个文件没加进 csproj 导致的编译错误在 SDK-style 项目里几乎不会出现。同时 csproj 文件从几百行缩减到几十行Git 合并冲突的概率也小了很多。如果你现在打开一个 .NET 8 的 WebAPI 项目文件里面通常只有这些关键节点Project SdkMicrosoft.NET.Sdk.Web PropertyGroup TargetFrameworknet8.0/TargetFramework Nullableenable/Nullable ImplicitUsingsenable/ImplicitUsings /PropertyGroup ItemGroup PackageReference IncludeMicrosoft.EntityFrameworkCore.SqlServer Version8.0.10 / /ItemGroup /ProjectTargetFramework 指定目标框架Nullable 和 ImplicitUsings 是编译相关的两个语言特性开关PackageReference 声明 NuGet 依赖。没有 GUID、没有源文件列表、没有一堆属性组。这就是 SDK-style 带来的极简表达。1.3 dotnet CLI一套命令走天下项目格式变化之后命令行体验也随之统一。dotnet命令从 .NET Core 2.0 左右开始逐步完善现在基本成了 .NET 构建发布的标准入口dotnet build编译项目生成 DLL 和依赖。dotnet publish按指定的运行时和发布模式输出可部署产物。dotnet test运行测试项目。dotnet run本地直接运行项目。dotnet restore还原 NuGet 依赖。dotnet pack把项目打包成 NuGet 包。这些命令在 Windows、Linux、macOS 上行为一致而且可以直接嵌入 CI 流水线。比如 GitLab CI 的 job 里可以写build: stage: build script: - dotnet restore MyApp.sln - dotnet build MyApp.sln -c Release这在旧 .NET Framework 时代基本做不到。msbuild 虽然也能在命令行用但需要 Visual Studio 的 MSBuild 环境路径、属性、目标之间有很多隐藏前提。dotnet CLI 则是自包含的装了 .NET SDK 就有完整构建能力。这里我要补充一个实操心得早期很多人不习惯命令行总觉得 Visual Studio 的图形界面更直观。但一旦你开始做自动化部署dotnet CLI 的价值就立刻体现出来了。它让“构建”从“一个人的操作”变成了“一条流水线里的步骤”而且每次的输出是确定性的。1.4 统一框架一处构建多处运行.NET 5 之后的另一个大变化是框架统一。以前 .NET Framework 只能跑在 Windows 上.NET Core 跨平台但不包含 WPF/WinForms 这些桌面框架。现在net6.0、net7.0、net8.0这些 TFM 成为统一的基线同一套基础库同时覆盖 Web、云原生、桌面Windows、移动MAUI、IoT 等场景。这意味着路径你不再需要为“Windows 上的 .NET Framework 4.8”和“Linux 上的 .NET Core 3.1”分别写两套代码和两套发布脚本。一个net8.0的 WebAPI 项目在 Linux 和 Windows 上都能构建也能按目标运行时输出不同平台的可执行文件。但框架统一不等于“免部署”。默认的dotnet publish是框架依赖发布即产物需要目标机器上装有对应版本的 .NET 运行时。如果你不想依赖目标机器环境就需要考虑自包含发布、单文件发布、AOT 发布。这些发布模型的选择就是现代 .NET 构建和发布方式革新的第二个核心点。2. 现代 .NET 发布模型详解框架依赖、自包含、单文件与 AOT发布方式和构建是两个紧密相关但不同的话题。构建是生成程序集发布是生成“能跑起来的一堆东西”。现代 .NET 的发布模型非常灵活但也容易让新手选错。我用一张表先做个对比发布模式产物大小目标环境要求适合场景框架依赖FDD小目标机需安装对应 .NET 运行时内网服务器、可控环境最常用自包含SCD较大无需安装运行时客户端分发、不方便装运行时的服务器单文件中等取决于是否包含原生运行库工具类程序、快速分发Native AOT最小不需要运行时启动极快无容器受限环境、性能敏感服务这几种模式不是互相排斥的。自包含和单文件可以同时开启AOT 发布天然就是自包含单文件。选择的关键在于你对部署环境有多少控制权以及对产物大小和启动性能的要求。2.1 RuntimeIdentifier 和 RID 的选择这个参数决定了产物跑在什么平台发布之前需要理解一个核心概念RuntimeIdentifier简称 RID。它用来描述目标操作系统和 CPU 架构例如win-x64、linux-x64、osx-arm64。指定了 RID 之后dotnet 才会为对应平台生成原生可执行文件比如 .exe 或者无扩展名的 ELF 文件而不是仅仅产出跨平台的 DLL。常见的发布命令是这样dotnet publish MyApp.csproj -c Release -r linux-x64 --self-contained true-c Release指定 Release 配置-r linux-x64指定目标平台--self-contained true表示自包含。如果你要在 Docker 里跑这个命令几乎是标准动作。这里我踩过一个坑不指定 RID 时dotnet publish默认做框架依赖发布产物里只有 DLL、依赖和宿主可执行文件如果目标服务器没装 .NET 运行时就会报You must install or update .NET runtime。所以决定发布方式时先想清楚到底是“我自己带运行时”还是“让服务器装运行时”这决定了要不要加-r和--self-contained。对于常见的 RID我还列几个容易混淆的点linux-x64适用于绝大多数 x86_64 的 Linux 服务器比如 Ubuntu、CentOS、Debian。linux-arm64适用于 ARM64 服务器比如 AWS Graviton、腾讯云 ARM 机型以及 RK3588 这类开发板。osx-arm64是 Apple Silicon Mac 的发布目标。如果你用win-x64发布生成的是带 .exe 的可执行文件但如果你的目标是 Linux一定不要乱用 RID否则产物跑不起来。2.2 单文件发布的坑与配置从 .NET 5 开始单文件发布逐步完善。所谓单文件就是把托管 DLL 和宿主打包成一个可执行文件。对面向外分发的工具来说非常方便一条命令能把整个程序发出去。单文件的配置有两种方式命令行参数或者 csproj 属性。我更推荐在 csproj 里直接写属性这样构建逻辑和代码仓库绑定在一起后续 CI 里可以少传一堆参数。PropertyGroup PublishSingleFiletrue/PublishSingleFile SelfContainedtrue/SelfContained RuntimeIdentifierlinux-x64/RuntimeIdentifier /PropertyGroup但单文件不是免费的。首先某些需要解压到磁盘的 Native 库、依赖原生命令的工具可能不能直接打包需要在运行时解压到临时目录。其次单文件发布后有些动态加载程序集的行为比如Assembly.LoadFrom会受影响因为所有 DLL 都被嵌入进主可执行文件了。所以如果你用了插件化的反射加载架构建议先做一轮兼容性测试。更隐蔽的问题是单文件发布时AppContext.BaseDirectory指向可执行文件所在目录这一点通常没问题但如果你依赖Directory.GetCurrentDirectory()请注意工作目录和程序目录不一定相同这和旧 .NET Framework 时代的习惯完全不同。2.3 自包含发布与运行时裁剪自包含发布最直观的优点是“服务器上不用装 .NET”。它会把整个运行时打包进发布产物。代价是体积变大通常一个最小的控制台程序也有六七十 MB。如果你对体积敏感可以开启裁剪PublishTrimmed。裁剪的机制是在发布时分析程序集引用把没有被代码路径使用到的框架程序集成员去掉。听起来很美好但反射是裁剪的天敌。你用反射访问的类型、方法、属性分析器不一定能识别出来就可能在运行时抛MissingMethodException、TypeLoadException之类的错误。所以我的建议是如果是简单工具类应用或者容器镜像对体积有严格要求可以尝试裁剪。如果是复杂业务系统尤其是用了反射、序列化、动态代理的框架比如某些 ORM、AOP 容器裁剪的收益赶不上排查问题的成本。自包含发布的另一个问题在于版本升级。框架依赖模式下服务器升级一次 .NET 运行时所有部署的应用都能受益自包含模式下每个应用都携带着自己的运行时安全补丁需要每个应用重新发布。这也是一种运维负担。2.4 Native AOT革新的下一个风口.NET 7 引入、.NET 8 逐步成熟的 Native AOT 发布是“再次革新”里最激进的一步。简单说AOT 编译在发布时直接把 IL 编译成本机代码不需要 JIT不需要运行时托管堆之外的大量元数据从而带来更快的启动速度、更低的内存占用甚至不需要目标机器安装 .NET 运行时。命令也很简单dotnet publish -c Release -r linux-x64 -p:PublishAottrue但 AOT 的限制同样明显。最核心的限制是动态代码生成System.Reflection.Emit在 AOT 下基本不可用很多依赖动态代理的库比如某些 Mock 框架、某些轻量级 ORM会直接不能用。另外AOT 编译产物对平台非常敏感aarch64 的程序不能跑在 x64 上Windows 的 AOT 程序也不能直接放到 Linux 上跑。我的个人判断是API 网关、批处理任务、CLI 工具、边缘计算这类场景非常适合 AOT。大型业务 Web 应用除非你已经把反射和动态加载的坑填完否则暂时不要盲目上 AOT。等 .NET 10 里的 AOT 兼容性再成熟一点再做迁移也不迟。3. 构建本地依赖与可复现构建把“在我电脑上能跑”变成“在哪都能跑”现代 .NET 的构建不只是让项目能编译通过更重要的是让构建过程可复现、可审计。这一节我想讲依赖管理因为很多构建问题的根源都不是代码本身出错而是依赖版本漂移、私有包源不通、本地缓存过期这些问题。3.1 PackageReference 与传递依赖别再把 DLL 塞进仓库过去 .NET Framework 项目常见的做法是引用 DLL把packages文件夹或者lib目录直接提交到仓库里。这种方式在团队协作中极易出错两个开发者的 DLL 版本不同构建结果就不一致包更新之后可能忘了提交甚至会出现“我的本地能跑CI 上编译不过”这种经典的“在我电脑上能跑”问题。现代 .NET 的做法是使用 NuGet 包引用。项目文件里写PackageReference只记录包名和版本构建时通过dotnet restore下载依赖。实践中我强烈建议把obj、bin这些目录加入.gitignore禁止把编译产物和 NuGet 包目录提交进仓库。仓库里只保留源码和项目文件这才是可复现构建的第一步。3.2 从 Directory.Build.props 到 Central Package Management依赖管理的一个痛点是版本不一致。一个解决方案里有十个项目每个项目都可能引用不同版本的同一个包。虽然 NuGet 有自己的冲突解决规则但版本差异带来的行为漂移很难排查。这时候可以用两个机制第一个是Directory.Build.props它可以在解决方案根目录为所有项目统一注入 MSBuild 属性。比如统一LangVersion、Nullable、ImplicitUsings还可以统一包版本。不过这个文件本质上只是 MSBuild 属性不是 NuGet 的正式版本管理机制。第二个是 .NET 8 之后默认推荐的中央包管理Central Package Management简称 CPM。在解决方案根目录放一个Directory.Packages.props集中声明所有依赖包的版本项目文件里的PackageReference只写包名不写版本。比如Project PropertyGroup ManagePackageVersionsCentrallytrue/ManagePackageVersionsCentrally /PropertyGroup ItemGroup PackageVersion IncludeMicrosoft.EntityFrameworkCore Version8.0.10 / PackageVersion IncludeNewtonsoft.Json Version13.0.3 / /ItemGroup /Project项目里这样引用ItemGroup PackageReference IncludeMicrosoft.EntityFrameworkCore / /ItemGroup这样做的好处是升级一个公共依赖版本时只需要改一个文件不会出现“A 项目升到新版本、B 项目还留在旧版本”的割裂状态。尤其是那些有十几个微服务的解决方案中央包管理能把依赖升级成本压到最低。3.3 锁定依赖版本packages.lock.json即使有了中央包管理传递依赖仍然可能悄悄变化。例如你直接引用了 A 包A 依赖 B 包的某个版本范围而 B 包之后发了一个新版本在 CI 时间点拉到的 B 就会和你本地不同。这种“非直接锁定”的问题常规写在 package 版本文件里的配置是防不住的。解决办法是启用依赖锁定文件。在项目文件里加上PropertyGroup RestorePackagesWithLockFiletrue/RestorePackagesWithLockFile /PropertyGroup启用后首次dotnet restore会生成packages.lock.json里面记录了完整依赖树。之后每次 restore 都会校验依赖树与锁定文件不一致时会报错或提示除非你显式执行dotnet restore --force-evaluate更新锁定文件。这个机制在 CI/CD 中的价值非常大。团队里很多人遇到过“本地通过、CI 失败”的问题绝大多数不是因为代码而是因为 NuGet 源上某个依赖的小版本漂移。锁定文件把依赖树固定下来构建的一致性会高很多。3.4 本地依赖与私有 NuGet 源离线构建到底怎么处理热词里有“构建本地依赖”我理解不是指把 DLL 放进仓库而是指“无外网环境下的依赖还原”。很多企业内网服务器不能直接访问 nuget.org这时候就需要搭建内网 NuGet 源或者使用离线包。常见的做法有三种在开发机上下载好.nupkg包放到一个共享文件夹或内网服务器上然后项目配置NuGet.config指向这个源。使用 Sonatype Nexus、Azure DevOps Artifacts、腾讯云 CODING 制品库等工具把公共源上的包代理或上传到内网源。把~/.nuget/packages全局包缓存整个打包拷贝到目标构建机然后通过NUGET_PACKAGES环境变量指定缓存路径。第三种方式最快但有一个隐蔽问题直接拷贝的包缓存可能缺少.nupkg.metadata等文件导致 restore 时认不出缓存里的包。所以我更建议用正规的木制品库方案。内网源配置在NuGet.config像这样configuration packageSources clear / add keymy-company valuehttp://192.168.1.100/v3/index.json / add keynuget valuehttps://api.nuget.org/v3/index.json / /packageSources /configuration注意clear /会清理所有默认源然后再添加自定义源。如果内网源不可用时希望回退到官方源就把两个源都加上根据可达性自动选择。不过源多了也有风险每一次 restore 都会轮询所有源速度会慢不少。4. GitLab CI/CD 中 .NET 项目的 Docker 镜像构建与自动化部署实战热词里出现“gitlab ci/cd中docker镜像构建与自动化部署实践”这恰好是 .NET 构建发布革新最典型的落地场景。现在 .NET 项目往前端化、容器化走构建产物从一堆 DLL 变成了一个 OCI 镜像部署时不用再关心服务器上装了哪个版本的运行时也不用人工拷贝文件。下面我把一套完整流程拆开讲。4.1 为什么现在更推荐“发布成镜像而不是拷 DLL”以前发布 WebAPI 是把dotnet publish的产物文件夹用 FTP 传到服务器然后在 IIS 里建站点指向目录。这个流程的问题在于“环境漂移”测试环境可能装了 .NET 8.0.1 的运行时生产环境可能只装了 8.0.0结果某个 API 在测试通过、生产报错。如果把应用和运行时一起做成 Docker 镜像运行时版本就固定在镜像的FROM mcr.microsoft.com/dotnet/aspnet:8.0这一行里。镜像内部是什么环境部署到哪都一样从根上解决环境漂移。GitLab CI 构建 .NET 镜像的常见流程是代码推送后由 CI Runner 执行 restore、build、publish再用产出的文件构建 Docker 镜像推送到私有镜像仓库最后触发部署环节。4.2 用多阶段构建控制镜像体积Dockerfile 是容器化发布的基石。我见过不少新手直接写FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY . . RUN dotnet publish -c Release -o /app/publish FROM mcr.microsoft.com/dotnet/aspnet:8.0 WORKDIR /app COPY --frombuild /app/publish . ENTRYPOINT [dotnet, MyApp.dll]这个能跑但不够优化。问题在于COPY . .把整个仓库包括.git目录、obj、bin都复制进构建上下文恢复依赖时又可能重复 restore。更好的做法是用“上下文加 .dockerignore 多阶段拷贝”。我习惯的 Dockerfile 长这样FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY [src/MyApp/MyApp.csproj, src/MyApp/] RUN dotnet restore src/MyApp/MyApp.csproj COPY . . RUN dotnet publish src/MyApp/MyApp.csproj -c Release -o /app/publish FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final WORKDIR /app COPY --frombuild /app/publish . EXPOSE 80 ENTRYPOINT [dotnet, MyApp.dll]先复制 csproj执行 restore再复制剩余源码。这样只要 csproj 和引用的项目文件没变Restore 步骤就可以命中 Docker 的层缓存构建速度会快很多。对于大型解决方案这一步优化能省下几分钟。还需要注意 .dockerignore**/bin **/obj .git .vs否则 obj 目录里的残留文件可能导致构建时出现莫名其妙的版本冲突。4.3 GitLab CI 流水线配置从镜像到部署以下是 .NET 项目在 GitLab CI 里构建 Docker 镜像并部署的一条完整流水线示例stages: - test - build - deploy variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA test: stage: test image: mcr.microsoft.com/dotnet/sdk:8.0 script: - dotnet test MySolution.sln build: stage: build image: docker:20.10.16 services: - docker:20.10.16-dind script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker build -t $IMAGE_TAG . - docker push $IMAGE_TAG deploy: stage: deploy image: docker:20.10.16 script: - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - docker pull $IMAGE_TAG - docker stop myapp || true - docker rm myapp || true - docker run -d --name myapp -p 8080:80 $IMAGE_TAG only: - main这里有几个细节值得说test阶段用 SDK 镜像跑dotnet test让测试跑在一致的环境里。build阶段使用docker:dind来构建镜像。GitLab Runner 默认不能直接调用宿主机的 Docker 守护进程所以需要 Docker-in-Docker 服务。IMAGE_TAG使用CI_COMMIT_SHORT_SHA保证每次构建的镜像有一个唯一标签方便回滚。deploy阶段先把旧容器停掉、删掉再启动新容器。这种粗暴替换方式对单机部署够用如果有多台机器就应该引入更高级的编排方案。如果你用的是阿里云、腾讯云等平台的容器服务也可以把 deploy 阶段替换成调用平台 API 触发镜像更新本质是一样的镜像推送成功才进入部署。4.4 发布 WebAPI 项目到 Linux 服务器一个直出命令的实操案例除了容器化很多团队仍然用传统方式部署到 Linux 服务器本地或 CI 上执行dotnet publish然后用 scp/rsync 把发布产物传到服务器再用systemd或 supervisor 托管进程。这也是完全可行的而且相比 Docker 更轻量。我的标准流程是dotnet publish MyApp.csproj -c Release -o /tmp/myapp-publish rsync -avz /tmp/myapp-publish userserver:/opt/myapp ssh userserver sudo systemctl restart myapp服务器上的 systemd 服务文件可以这样写[Unit] DescriptionMy .NET WebAPI Afternetwork.target [Service] WorkingDirectory/opt/myapp ExecStart/usr/bin/dotnet /opt/myapp/MyApp.dll Restartalways RestartSec10 EnvironmentASPNETCORE_ENVIRONMENTProduction [Install] WantedBymulti-user.target注意这种发布方式默认是框架依赖发布服务器上必须安装对应版本的 .NET Runtime。如果你不想依赖服务器环境用-r linux-x64 --self-contained true发布服务器上就只需要保留发布产物连 ASP.NET Core 运行时都不用装。不过自包含发布后的目录比较大rsync 时建议排除*.pdb文件减小传输体积rsync -avz --exclude *.pdb /tmp/myapp-publish userserver:/opt/myapp我在实际项目中还遇到过一个问题WebAPI 通过 systemd 启动时如果应用监听端口是 5000但是服务器防火墙只开放了 80外部访问不通。解决方案是在 appsettings.json 里明确配置 Kestrel 监听地址或者在 systemd 里设置环境变量ASPNETCORE_URLShttp://0.0.0.0:8080。这类“发布后跑不起来”的问题多数不是发布本身的问题而是运行环境没配好。5. 常见问题与排查技巧实录dotnet 构建发布路上的十来个坑最后一部分我按实际踩坑经验把 .NET 构建发布过程中最常见的问题整理成速查表每一条都附带排查思路。因为构建发布的问题往往看起来千奇百怪但根因一般都在下面这几类里。5.1 NuGet 还原失败NU1108、NU1301、本地缓存损坏NuGet 还原失败是最高频的构建错误之一。报错信息比如NU1108: Cycle detected大多是项目之间循环引用NU1301: Unable to load the service index for source一般是私有源地址不可达或者网络不通。排查步骤我总结为四步先看NuGet.config里配置了哪些源确认源地址是否还能访问。在命令行执行dotnet restore --force绕过缓存重新还原。如果报错包版本不存在到 NuGet 源上确认包名、版本、大小写是否准确。清空本地全局包缓存dotnet nuget locals all --clear。如果是在 Docker 构建中报 NU1301很可能是容器内网络访问不了外部源。此时可以配置代理或者使用内网源。注意构建镜像时RUN dotnet restore默认走容器网络如果 CI Runner 本身能访问外部源但 dind 容器访问不了那多半是 Docker 网络的 DNS 配置问题。5.2 跨平台 RID 引发的问题NETSDK1005 / 运行时找不到很多人在 Linux 上构建时没指定 RID或者指定了win-x64但要在 Linux 下运行结果一脸懵。NETSDK1005错误通常是因为指定的 RID 与目标框架不兼容或者 SDK 不认识这个 RID。我建议在解决方案根目录放一个Directory.Build.props统一指定默认发布配置Project PropertyGroup RuntimeIdentifierslinux-x64/RuntimeIdentifiers /PropertyGroup /Project这样团队内所有成员构建时默认目标平台就是 linux-x64减少“本地能跑服务器跑不了”的情况。如果你要同时支持多个平台把多个 RID 用分号分隔写在RuntimeIdentifiers属性里但注意一次 publish 最好只指定一个RuntimeIdentifier否则产物会混杂。5.3 单文件发布后原生库找不到单文件发布模式下有些原生依赖比如 SQLite 的e_sqlite3原生库需要解压到临时目录才能加载。默认情况下 .NET 会处理这种解压逻辑但在某些容器镜像、无写权限目录下会失败。解决办法是在 csproj 里配置PropertyGroup IncludeNativeLibrariesForSelfExtracttrue/IncludeNativeLibrariesForSelfExtract /PropertyGroup这样会将原生库也嵌入单文件运行时自动解压到临时目录。如果仍然失败检查应用是否以只读文件系统运行比如某些安全容器会把/tmp设置为 noexec。这种情况下单文件方案可能就不适合建议退回普通的自包含发布。5.4 AOT 发布与反射冲突AOT 发布时如果遇到类似System.Reflection.Emit相关错误基本可以断定是动态代码生成被 AOT 限制住了。不要第一时间想着怎么绕过先检查代码里是否有以下模式使用Activator.CreateInstance(Type)动态创建类型。用Assembly.GetType()、Assembly.LoadFrom()动态加载程序集。使用dynamic关键字。使用Expression.New或Expression.Lambda构建表达式树并编译。使用某些依赖动态代理的第三方库。遇到这些情况要么裁剪配置里加入DynamicDependency特性要么放弃 AOT改回 JIT 模式。我个人在迁移一个控制台工具时为了兼容一个第三方库最后选择保持 JIT 发布而不是硬上 AOT。有些性能收益不值得引入额外的兼容性风险。5.5 构建时的网络错误与证书问题.NET 构建过程中经常遇到形如net::err_incomplete_chunked_encoding这类网络错误虽然这是浏览器里的常见报错但在 CI 中也有类似现象NuGet 下载中断、Docker 拉取镜像超时。多数原因是网络不稳定、代理层中断连接、或者下载速度太慢导致连接超时。解决方案通常围绕三点使用国内镜像源或者内网源降低对默认公共源的依赖。在 NuGet 客户端配置超时时间比如dotnet restore --disable-parallel避免并发下载导致网络拥塞。在 Docker 构建中设置构建参数为dotnet restore单独配置一个可复用的缓存卷。另外如果公司自建了 NuGet 源并使用 HTTPS证书链不完整会导致Authentication failed之类的错误。这种情况不是代码问题而是源服务器的证书配置问题需要找运维同事把证书链补全。5.6 Web 项目发布后的启动失败ORA-28547 等外部连接错误热词里有一条ora-28547: connection to server failed, probable oracle net admin error这虽然不是 .NET 构建的直接问题但 .NET WebAPI 项目发布到服务器后经常会遇到数据库连接失败。这条 Oracle 错误通常意味着客户端和服务器之间的 Oracle Net 配置有问题常见原因有Oracle 客户端版本不兼容、tnsnames.ora配置错误、防火墙拦截了 1521 端口。在 .NET 环境里排查 Oracle 连接问题时我建议先检查环境变量ORACLE_HOME、TNS_ADMIN是否正确设置。如果用了托管 ODP.NETOracle.ManagedDataAccess则不需要安装 Oracle Client但仍需要配置连接字符串里的 Data Source 指向正确的服务名。这类问题的共性是“发布成功了但应用没法连上外部依赖”所以做发布检查时除了进程是否起来还要确认应用能连通数据库、Redis、消息队列等外部组件。5.7 Git 与构建的协作问题避免 obj/bin 冲突最后说一个特别基础但很多人反复踩的坑刻意把obj和bin提交进代码仓库。这样做的后果是在 CI 上构建时旧版本的中间产物可能会干扰新代码的编译导致一些诡异的“改了代码但不生效”的问题。正确做法是严格执行.gitignorebin/ obj/ *.user .vs/在 CI 里构建时最好也先清理工作目录。GitLab CI 的 Runner 默认会拉取最新代码到全新目录但本地多人协作时如果本地没有清掉旧的 bin/obj偶尔也会遇到duplicate或版本不一致的编译错误。这时候执行一次dotnet clean或者直接删除bin、obj目录再 build通常能解决。写在最后的一点个人体会这些年在 .NET 构建发布这条路上折腾下来我最深的体感是革新的方向其实非常明确就是把“依赖开发的个人环境”变成“依赖可重复的流程”。不管是 SDK-style 项目、dotnet CLI、单文件发布、Docker 镜像、GitLab CI还是中央包管理本质上都是在消灭不确定性。你不再需要记“项目里每个文件都要加进工程文件”这种潜规则也不再需要担心“服务器上的运行时版本不一样导致挂了”。只要把构建和发布的规则写进代码仓库里换任何一个人、任何一台机器来执行产出都一样这才是现代构建该有的样子。这一篇我从整体演进讲到发布模型再到依赖管理和 CI/CD 落地内容已经不少。下一篇我打算深入讲一讲 Native AOT 在真实业务里的取舍以及 .NET 10 对发布体验的进一步优化包括这些变化在实际项目里怎么落地。如果你正在做 .NET 构建或发布相关的改造希望这篇能给你一个清晰的路线图。