VS Web Site 项目编译卡住排查指南

1. 现象与核心结论

当使用 Visual Studio 编译 ASP.NET Web Site 项目时，如果进度长时间卡在“正在验证网站”，这几乎从来不是代码本身的问题。

其根因是 ASP.NET 网站项目整站校验这项繁重的任务，被安全软件实时扫描冷缓存、.NET NGEN 镜像失效、临时缓存全量重建等环境因素放大后的性能瓶颈。排查时应优先检查环境因素，再怀疑代码缺陷。

项目类型差异：此步骤仅存在于 Web Site 项目（包含 website.publishproj、App_Code，无 .csproj 文件）中；Web Application 项目不会触发此步骤。
全量校验原理：Visual Studio 会调用 aspnet_compiler.exe，对整站所有的 .aspx、.ashx、.ascx、.master 文件以及 App_Code 进行全量编译和校验。
性能瓶颈：随着文件数量增加（例如数百个页面文件和类文件），校验速度会显著下降。若 web.config 中配置了 debug="true"，系统会按调试模式进行编译，进一步拖慢速度。因此，该步骤天生耗时较长，极易因环境扰动演变为“疑似卡死”。

为什么系统更新或重启后，编译会突然变卡？通常由以下三类触发器导致：

触发器	原理	核心特征
安全软件实时扫描	更新重启后，安全软件（如火绒 `HipsDaemon`）的监控缓存冷启动，整站校验时读写上万个文件被逐一拦截扫描。	安全软件进程 CPU/磁盘占用极高，而编译进程占用极低。
.NET NGEN 原生镜像失效	系统安全更新导致预编译的 NGEN 镜像失效，`aspnet_compiler/csc` 退化为 JIT 编译；同时后台 `mscorsvw.exe` 进程抢占资源重建镜像。	任务管理器中可见 `mscorsvw.exe` 进程高负载运行。
临时缓存失效	更新操作清空或导致 `Temporary ASP.NET Files` 缓存失效，编译过程从“增量编译”转变为“全量重编”。	首次编译极慢，后续编译速度恢复正常。

排查技巧 (卡死 vs 变慢)：打开任务管理器观察 aspnet_compiler.exe 或 csc.exe 的 CPU 使用率。如果数值有跳动，说明只是慢，请耐心等待；如果 CPU 长时间（>15分钟）为 0%，则是真阻塞（卡死），需要清理缓存重试。

遇到该问题时，可按性价比从高到低执行以下方案（无需修改业务代码）：

配置安全软件信任区（见效最快）
- 目录白名单：将开发项目目录、Temporary ASP.NET Files 目录以及 %LOCALAPPDATA%\Temp 添加到白名单。
- 进程白名单：将 devenv.exe、MSBuild.exe、aspnet_compiler.exe、csc.exe、VBCSCompiler.exe 添加到信任进程。
手动触发 NGEN 镜像重建
- 以管理员身份运行命令提示符，执行 ngen.exe executeQueuedItems（建议 32 位和 64 位的 .NET Framework 目录下各执行一次）。
关闭“生成前整站验证”（长期提速）
- 在 Visual Studio 中，打开网站属性页 -> 生成选项卡。
- 将“运行起始页前”设置为 不生成 或 只生成当前页。在最终发布时再执行完整的整站验证。
清理临时缓存并重建
- 关闭 Visual Studio。
- 清空 Temporary ASP.NET Files 目录及相关的临时缓存。
- 重新打开项目并执行一次全量生成进行预热。

在编译卡住时，往往会伴随一些警告信息。它们是独立的小问题，切勿被其误导排查方向：

告警：无法更新自动刷新引用 sqlsugar.dll，找不到 ...
- 原因：bin\SqlSugar.dll.refresh 文件指向了已删除的旧版本路径，但 bin 目录下的 DLL 实体仍然存在，因此不影响编译。
- 处置：将 .refresh 文件的内容修改为当前正确版本的相对路径（例如 ..\packages\sqlSugar.x.x.x\lib\SqlSugar.dll）。
告警：CS0168 / CS0162（未使用变量 / 不可达代码）
- 原因：无害的编译器警告，完全不影响系统运行。
- 处置：遵循“不擅改线上代码”的原则，保留原样即可。