又到周末了按惯例把这周 .NET 圈子里值得聊的东西理一理。2025年12月第2期热词榜上既有 .NET 11 和 .NET 10 的版本之争也挤满了 Docker 拉镜像、nginx 反代证书这类部署实战问题还有不少人被 ArcGIS、PUBG 里那个老掉牙的 .NET Framework 3.5 反复折磨。这期周刊我换个思路不按新闻流罗列直接按“能解决什么问题”来分组你挑自己踩到的坑看就行。1. 版本动向.NET 11 与 .NET 10 怎么选以及 Hosting Bundle 的坑1.1 版本定位差异LTS 与 STS 的真实区别这周热词里“.NET11 和 .NET10 的区别”被翻来覆去地问说明很多人正在做技术选型被这两个版本号绕晕了。先说结论如果是要上生产、要长期维护的项目优先考虑 LTS 版本如果是想尝鲜、做实验、写开源组件可以跟进 STS 版本。.NET 10 是 LTS长期支持支持周期大约三年适合企业级应用、云原生服务这些“上线之后不能三天两头折腾”的场景。.NET 11 走的是 STS标准期支持路线支持周期短一些大概 18 个月好处是能更快用上最新 API、语言特性和运行时优化。两者的底层差异主要体现在STS 版本会引入更多实验性特性比如 AI 编排相关的库、更激进的 JIT 改进、新的 GC 配置模式这些在 LTS 版本里往往会被保守处理等到验证成熟了再合入下一个 LTS。我在实际项目里的建议很简单新项目默认先看 LTS把依赖锁定在 .NET 10 上如果发现某个新特性只有 .NET 11 才有而且是项目刚需那就单独评估升级成本不要因为“版本号大”就盲目追新。另外要注意.NET 10 和 .NET 11 可以在同一台机器上共存不用互相卸载别被“装新版本会覆盖旧版本”这种说法吓到。SDK 和 Runtime 是分开管理的项目文件里的 TargetFramework 才决定实际跑在哪个版本上。还有个容易被忽略的点C# 语言版本和 .NET 版本是绑定的但不是严格一对一。你在 .NET 10 项目里即使设了 LangVersion 为最新也未必能用 .NET 11 预览的新语法因为编译器版本和运行时 API 是配套的。折腾半天编译不过时先检查一下 TargetFramework 和 LangVersion 的匹配关系。1.2 IIS 部署必需的 Hosting Bundle热词里“.NET x hosting bundle download”也是高频搜索。Hosting Bundle 是给 IIS 用的运行时安装包它把 .NET 运行时、ASP.NET Core Module 和命令行工具打包在一起专门负责让 IIS 能反向代理到 Kestrel。很多人下载了纯 Runtime 装到 Windows Server 上发现 IIS 站点一直返回 502.3就是因为缺了 ASP.NET Core Module 这一层。下载时记住三个要点。第一版本必须匹配你发布时用的 TargetFramework 是 net10.0就装 .NET 10 Hosting Bundle不要图省事装个更高的万一 IIS 站点启动后进程直接退出八成是版本对不上。第二安装完必须执行 iisreset 重启 IIS否则模块列表不会刷新这个步骤我见过无数人漏掉。第三池化应用要检查“加载用户配置文件”和“启用 32 位应用程序”这两个设置很多 Hosting Bundle 装好后依然报错问题根本不在 Bundle而是应用池配置和项目发布方式不匹配。如果你用的是反向代理服务器而不是 IIS那 Hosting Bundle 其实不是必需品直接装 Runtime 就行了。把“需要 Bundle”和“需要 Runtime”这两个场景分清楚能少走很多弯路。2. 容器与反向代理本周网络问题集中盘点2.1 Docker 拉取镜像报错registry-1.docker.io/v2/ 连不上热词里出现“error response from daemon: get https://registry-1.docker.io/v2/”这是 Docker 默认从 Docker Hub 拉取镜像时连接失败。这个错误的本质是 Docker 守护进程访问 registry-1.docker.io 被网络环境挡住了可能是 DNS 解析问题也可能是防火墙或代理拦截。排查路径我按顺序操作先用 docker info 看 Docker 版本和存储驱动是否正常再用 ping registry-1.docker.io 或 nslookup 确认域名能不能解析。很多情况下DNS 被污染或不稳定导致 Docker 解析不到真实的 registry IP。这时候可以在 /etc/docker/daemon.json 里显式配置 DNS{ dns: [8.8.8.8, 223.5.5.5] }改完后 systemctl restart docker 再试。如果 DNS 没问题但还是超时那就要检查代理配置和网络策略。实际项目里最常见的解决方式是配置镜像加速器国内云厂商提供的镜像加速服务可以正常拉取大部分公共镜像只需要在 daemon.json 里加 registry-mirrors 字段{ registry-mirrors: [https://your-mirror-id.mirror.aliyuncs.com] }注意加速器和 Docker Hub 的同步有延迟如果拉的是很新的 tag偶尔会 404这时候可以先把镜像源切回官方再拉一次。这个错误还有个隐蔽变体在内网环境里公司自建了 Harbor 或 Nexus但 docker pull 时还是走了 Docker Hub十有八九是镜像地址写错了把完整仓库路径带上例如 registry.your-company.com/namespace/image:tag而不是只写 image:tag。2.2 nginx 反代后浏览器报证书错误net::err_cert_common_name_invalid“nginx 转发 https 反向代理 net::err_cert_common_name_invalid”这组热词来自典型的 HTTPS 配置问题。浏览器报这个错说明 TLS 握手成功但证书上的域名和访问地址对不上。最常见的原因有两个证书是给 api.example.com 签的结果你用 www.example.com 去访问或者证书配置正确但 nginx 转发时把 Host 头搞丢了。排查时先看证书本身openssl s_client -connect your-domain.com:443 -servername your-domain.com这个命令会输出证书的 CN 和 SAN。如果 CN 不是当前访问域名那就是证书申请错了去换一张。如果证书没问题那就是请求头的问题检查 nginx 配置里的 proxy_set_headerserver { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/your-domain.crt; ssl_certificate_key /etc/nginx/ssl/your-domain.key; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }关键就是 proxy_set_header Host $host如果把这行改成 $proxy_host 或写死成别的域名后端虽然能收到但客户端已经先看到了证书域名和地址不一致。另外要提醒一个细节证书链如不完整浏览器会报 err_cert_authority_invalid和这个错误码容易混淆。把中间证书和根证书一起合到 crt 文件里顺序是“域名证书 - 中间证书”不能倒。2.3 HTTP/2 协议报错与 URL scheme 拦截net::err_http2_protocol_error 这周也频繁出现。这个错误码在我经手过的项目里基本是两种场景一种是 nginx 配置了 http2但没配置好 TLS 扩展导致客户端尝试 HTTP/2 升级失败另一种是后端服务不支持 HTTP/2而客户端强行用了 h2 协议尤其是前端用 fetch 这种 API 时会暴露得更明显。最直接的临时解决方法是把 listen 443 ssl http2 改成 listen 443 ssl禁用 HTTP/2 回到 HTTP/1.1业务功能通常不受影响。想彻底解决需要确认后端各组件是否都支持 h2比如负载均衡到 Kestrel 本身是没问题的但如果中间混了一层老版本 Nginx 或某些云负载均衡就要统一版本。net::err_unknown_url_scheme 则是另一类问题WebView 或前端框架遇到不认识的 URL scheme比如应用内跳转被写成了 intent:// 或 weixin://浏览器不认这个协议直接拦截。做 App 内嵌页面时可以在 WebView 的 shouldOverrideUrlLoading 里处理对应 scheme或者前端跳转前先判断平台。net::err_blocked_by_orb 相对少见它是 Chromium 的 ORBOpaque Response Blocking机制在起作用目的是防 Spectre 类攻击浏览器拦截了跨域读取 no-cors 资源的响应体。遇到 fetch 报这个错解决方向是后端加上正确的 CORS 头把请求模式改成 cors 而不是 no-cors如果业务上确实需要流式读取且没法改后端就只能用代理转发来规避。3. 老框架兼容性.NET Framework 3.5 与 CLR 那些事3.1 ArcGIS 10.2 和 PUBG 为什么都盯着 .NET Framework 3.5热词里出现了“arcgis 10.2 桌面版运行需要依赖微软 .net framework 3.5 sp1”和“打开 pubg 时 net framework 3.5”。这俩项目八竿子打不着但问题一模一样它们在 Windows 10/11 上需要 .NET Framework 3.5 SP1而这个组件默认不启用。为什么 ArcGIS 10.2 这么老还要求 3.5因为这版软件是在 2013 年发布的开发时基于 .NET Framework 3.5 写了很多扩展尤其是 ArcObjects 组件全面依赖 WPF 之前的图形栈和旧版序列化机制这些后来没有迁移到 4.x。PUBG 的情况类似游戏的反作弊组件、启动器某些模块仍编译为 .NET 2.0/3.5 时代的目标框架所以系统里没装就跑不起来。启用方式很简单但很多人找不到入口。控制面板 - 程序和功能 - 启用或关闭 Windows 功能勾选“.NET Framework 3.5包括 .NET 2.0 和 3.0”点确定。这个操作会请求 Windows Update 下载组件如果机器无法联网可以用离线方式dism /online /enable-feature /featurename:NetFx3 /all /source:D:\sources\sxs /limitaccess这里的 source 路径是系统安装镜像中提取的 sources\sxs 目录。我处理过不少现场环境这种 dism 方式最靠谱因为旧版组件不通过 Windows Update 时经常因为组策略或更新服务器问题失败。装好后 .NET Framework 3.5 和 4.x 可以共存它们运行在不同 CLR 版本上互不干扰。3.2 SQL Server 中 CLR 被禁用怎么启用热词“execution of user code in the .net framework is disabled. enable clr enable”这句话基本可以判定是在 SQL Server 里执行 CLR 存储过程或自定义聚合函数时报的错。SQL Server 默认禁用 CLR 集成需要显式开启EXEC sp_configure clr enabled, 1; RECONFIGURE;但这里有个新的坑SQL Server 2017 以后引入了 clr strict security即使 clr enabled1老的程序集也可能被拒。需要额外设置EXEC sp_configure show advanced options, 1; RECONFIGURE; EXEC sp_configure clr strict security, 0; RECONFIGURE;严格模式关闭后再用 CREATE ASSEMBLY 加载自定义 DLL。不过我要提醒一句CLR 集成虽然强大但在数据库里跑 C# 代码安全边界和稳定性都得特别谨慎。权限控制要锁定到数据库级别DLL 必须来自可信来源能用 T-SQL 解决的尽量别用 CLR这是我在生产环境里踩过坑后养成的习惯。另外开启 CLR 之前先评估 SQL Server 版本和补丁等级某些老版本对高版本 Framework 编译的程序集支持有限可能刚开启就遇到权限异常。3.3 离线安装与 AIO 整合包的风险提示热词“microsoft .net packages aio”指的是把 .NET Framework 各版本整合在一起的离线安装包看起来方便但使用前要留个心眼。AIO 包通常是把 3.5、4.0、4.5、4.6、4.7、4.8 这些离线包打成一个合集适合内网批量部署。问题在于来源不确定性如果从非官方渠道下载可能包含修改过的安装脚本轻则安装失败重则有安全风险。我的建议是优先从微软官方下载中心拉取对应的独立安装包各版本离线安装包的体积都不大加在一起也就几百 MB完全没必要用第三方整合包。如果企业内网确实需要可以先在隔离环境里抓包验证安装程序的数字签名和哈希值再分发到生产机器。还有一点某些老旧软件比如 ArcGIS对 .NET Framework 的版本判断逻辑很死板即使装了 .NET 4.8它也只看注册表里有没有 3.5 的条目所以不要试图用新版 Framework 替代旧版。该装 3.5 就装 3.5硬凑没有意义。4. 配置体系实战Microsoft.Extensions.Configuration 使用要点4.1 从 JSON 到环境变量的优先级“c# .net microsoft.extensions.configuration”这组热词指向 .NET 的配置体系。这个库是 .NET Core/5 之后所有应用配置的基石支持 JSON、XML、INI、环境变量、命令行、内存对象等多种配置源。很多新手用了一两年都是“模板自带什么就改什么”没搞懂配置源之间的覆盖关系结果在容器环境里出现“改了环境变量但程序还是读旧值”的诡异问题。配置源的优先级取决于注册顺序后注册的覆盖先注册的。一般来说命令行参数优先级最高其次是环境变量再是 JSON 文件最低是代码里的默认值。我常用的基础写法如下var builder new ConfigurationBuilder() .SetBasePath(Directory.GetCurrentDirectory()) .AddJsonFile(appsettings.json, optional: false, reloadOnChange: true) .AddJsonFile($appsettings.{Environment.GetEnvironmentVariable(ASPNETCORE_ENVIRONMENT) ?? Production}.json, optional: true, reloadOnChange: true) .AddEnvironmentVariables() .AddCommandLine(args); var configuration builder.Build(); var connectionString configuration.GetConnectionString(DefaultConnection);注意两个细节。第一AddEnvironmentVariables 默认只读环境变量不支持前缀过滤如果想读自定义前缀的变量可以这样.AddEnvironmentVariables(MYAPP_)这样一来环境变量 MYAPP__ConnectionStrings__DefaultConnection 会映射到配置键 ConnectionStrings:DefaultConnection。注意环境变量里双下划线对应配置键里的冒号分隔层级。第二reloadOnChange 只对文件类配置源生效环境变量和命令行参数不支持热重载需要自己实现监听逻辑。4.2 Options 模式与热重载配置读到了但代码里到处用 configuration[xxx] 字符串索引这是我很不推荐的做法维护起来太痛苦。更好的方案是 Options 模式把配置节绑定为强类型对象public class MyOptions { public string Endpoint { get; set; } public int RetryCount { get; set; } public bool EnableLogging { get; set; } }在 DI 容器里注册services.ConfigureMyOptions(configuration.GetSection(MyOptions));使用时通过 IOptions 、IOptionsSnapshot 或 IOptionsMonitor 注入。三者的区别是IOptions 是单例启动时固定IOptionsSnapshot 在每次请求时读取当前值支持热重载IOptionsMonitor 可以监听变更事件适合后台服务或长时间运行的任务。实际项目中我重点推荐 IOptionsSnapshot因为它兼顾了热重载和请求一致性同一个请求内读到的值是一致的但不同请求之间能感知配置变化。而 IOptionsMonitor 适合用来实现“配置变了就自动刷新某段逻辑”的全局功能。遇到“改了 appsettings.json 但程序没生效”的问题时检查两处AddJsonFile 有没有开 reloadOnChange以及注入的是不是 IOptionsSnapshot/IOptionsMonitor。如果用的是 IOptions那永远等不到重载。Options 模式还有一个高级用法是命名配置和配置验证比如数据库链接串在不同环境不同实例可以用命名 Options 区分配合 ValidateDataAnnotations 自动校验必填字段配置缺失时启动阶段直接抛异常而不是运行到一半才出错。这个机制能帮你提前拦截很多环境差异问题。5. 本周问题速查与操作实录5.1 MySQL 服务无法启动的排查过程热词“net start mysql mysql 服务无法启动”是老朋友了几乎每周都能看到。这个问题的典型规律是要么刚装完 MySQL 第一次启动就失败要么跑得好好的突然启动失败。前者多是因为没有初始化数据目录后者多是配置变更或磁盘问题。新装环境的排查路径我整理成一套固定流程用管理员权限打开命令提示符执行 net start mysql记录具体错误码。最常见的是“服务无法启动服务没有报告错误”这一步信息量很少要往下查。打开 MySQL 错误日志路径在 my.ini 里配置的 log-error默认可能在数据目录下的 hostname.err。看日志最后几行如果有“Cant find file: mysql.ibd”或者“Table mysql.plugin doesnt exist”那就是初始化没做好执行mysqld --initialize-insecure如果日志提示“InnoDB: Operating system error number 13”大概率是数据目录权限不对。Windows 下给 MySQL 服务账户设置数据目录的完全控制权限Linux 下检查属主是否 mysql 用户。如果是端口被占用导致启动失败用 netstat -ano | findstr 3306 找到占用进程杀掉或改 my.ini 的 port 配置。补充一个我踩过的坑my.ini 里的路径写法很坑比如 basedir 和 datadir 用了反斜杠结尾或路径带中文启动时就会静默失败。建议把路径统一写成正斜杠例如basedirC:/mysql-9.0 datadirC:/mysql-9.0/data port3306还有 MySQL 8.0 以后默认认证插件是 caching_sha2_password老项目客户端不支持时服务能启动但连接报 1045 或 2059解决办法是在初始化时用 --default-authentication-pluginmysql_native_password或者给特定用户指定认证插件。遇到“net start mysql”失败急得满头大汗时先深呼吸错误日志里基本都写了真实原因。5.2 网络错误码速查表我把这周热词里的浏览器端错误码汇总成一张表方便你翻查错误码含义常见原因解决方向net::err_cert_common_name_invalid证书域名不匹配证书 CN 和访问域名不一致 / Host 头丢失换证书 / 修正 proxy_set_header Hostnet::err_http2_protocol_errorHTTP/2 协议错误服务端不支持 h2 / 配置冲突临时禁用 http2 / 对齐组件版本net::err_unknown_url_scheme未知 URL schemeWebView 遇到 intent:// 等在 shouldOverrideUrlLoading 处理net::err_blocked_by_orb跨域读取被拦截ORB 机制阻止 no-cors 响应体后端加 CORS 头 / 代理转发这份速查表是我根据上下文直接归档的实际排查时还要带上下文看比如错误频繁出现时先用“错误码 触发界面”双重过滤能缩小定位范围。另外热词里还有“nginx 转发 https 反向代理 net::err_cert_common_name_invalid”这和我在第 2.2 节讲的场景完全一致不重复展开直接对照配置检查。5.3 其他值得提一句的热词这期还有一些杂项。“net模式与端口转发ros2”是 ROS2 多机通信相关的内容核心问题是 DDS 发现协议需要特定端口和网段Docker 容器里跑 ROS2 节点时如果用的是 bridge 网络节点之间经常互相发现不了解决办法要么用 host 网络模式要么手动配置 ROS_DOMAIN_ID 和 RMW_IMPLEMENTATION再配合端口映射。这块我不展开太多但提一句容器里跑 ROS2网络模式的选择基本决定了你 debug 的时间成本。“duplicate net names wire net”是 Docker 网络名称重复的问题创建网络时报 duplicate解决办法是先看现有网络列表docker network ls docker network rm 重复的名称如果你用了 docker-compose注意项目前缀两个 compose 文件在同一个网络时external 声明要一致否则容器能建但网络绑定对不上。“魔戒.net网站”“realme回退包链接”“net monitor for employees pro 6.4.6”这几个偏冷门。魔戒.net 是一个老牌爱好者向站点属于站长圈的文化遗产realme 回退包链接对应手机系统降级包强调地区版本和签名校验刷错了变砖风险挺高net monitor for employees pro 6.4.6 则是一款员工行为监控软件这类工具大多用 .NET 技术栈开发跑起来动静小但合规性需要格外注意别在自己电脑上随便试。编译错误 “execution of user code in the .net framework is disabled. enable clr enable” 对应 SQL Server 的 CLR 启用问题已在第 3.2 节专门讲过这里不再重复。本周周刊就写这些。我个人整理下来最大的感受是.NET 生态早就不是“装个 Framework 就能跑”的简单时代了版本选型、容器化部署、老框架兼容这三个话题看似分散内核都是“运行时环境不匹配”。把环境问题理清楚很多疑难杂症能少踩一半。