ASP.NET Core Boilerplate v5生产环境发布后运行报错如何解决

报错核心原因 #

你所列出的4个报错均属于前端JavaScript依赖加载异常类问题，本质是基础依赖库加载失败、引入顺序错误，导致后续依赖相关的变量、对象未被正常初始化：

• $ is not defined 代表jQuery基础库未加载
• Spin.js not present 代表spin.js加载动画库未加载
• moment is not defined 代表moment日期处理库未加载
• Cannot read properties of undefined (reading 'unspecifiedClockProvider') 是ABP框架脚本执行报错，因为前置的依赖库未加载，导致ABP全局对象未被正常初始化，无法读取内部的时钟相关配置属性

具体触发场景 #

• 发布时静态资源打包失败：ASP.NET Core Boilerplate v5默认使用Bundler & Minifier工具或gulp任务对前端资源做打包压缩，若发布过程中打包任务执行异常，会导致第三方JS库未被输出到发布后的wwwroot目录，或打包文件损坏
• 脚本引入顺序错乱：若近期修改过布局页_Layout.cshtml的脚本引入顺序，jQuery作为最基础的依赖必须放在最靠前的位置，之后依次引入spin.js、moment.js等第三方库，最后再引入ABP框架脚本和项目自定义脚本，顺序错误会导致后续依赖无法读取前置库暴露的全局变量
• 静态资源访问受限：服务器上wwwroot目录未给dotnet运行用户或IIS应用池用户配置读取权限，或是项目的静态资源中间件配置被修改，导致JS文件请求返回403/404状态码
• CDN资源加载失败：若项目使用CDN引入第三方JS库，服务器公网访问受限会导致CDN资源拉取失败，若没有配置本地降级逻辑就会触发变量未定义报错

排查步骤 #

• 打开浏览器开发者工具的网络标签页，刷新页面过滤查看所有JS资源的请求状态：
  • 状态码为404：对应JS文件不存在于服务器指定路径，或资源路径配置错误
  • 状态码为403：静态资源目录没有配置正确的读取权限
  • 状态码为500：静态资源请求触发了服务端异常
• 检查近期代码提交记录，确认是否修改过_Layout.cshtml的脚本引入顺序，或是删除过wwwroot/lib目录下的对应依赖文件
• 检查项目的打包配置文件（bundleconfig.json或gulpfile.js），确认jQuery、spin.js、moment.js都被纳入打包规则，且本地执行发布操作时打包任务没有抛出异常

修复方案 #

• 资源丢失修复：本地切换到发布模式运行项目，确认发布输出的wwwroot目录下所有JS依赖文件完整。若打包失败可先执行npm install还原所有前端依赖，再重新执行打包命令，确认资源完整后再发布到服务器
• 引入顺序修复：调整布局页的脚本引入顺序，确保依赖前置，参考顺序如下：

<!-- 基础依赖更靠前 -->
<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/spin.js/spin.min.js"></script>
<script src="~/lib/moment/min/moment.min.js"></script>
<!-- ABP框架脚本放第三方依赖之后 -->
<script src="~/lib/abp-web-resources/Abp/Framework/scripts/abp.js"></script>
<!-- 项目自定义脚本放最后 -->
<script src="~/js/site.min.js"></script>

• 权限与中间件配置修复：给服务器上的wwwroot目录配置dotnet运行用户/IIS应用池用户的读取与执行权限，确认Program.cs（.NET 5+）或Startup.cs中已正确注册静态资源中间件app.UseStaticFiles();，且注册位置在路由中间件之前
• CDN降级逻辑补充：若使用CDN引入依赖，补充本地 fallback 逻辑，避免CDN加载失败导致的报错，示例如下：

<script src="https://cdn.jsdelivr.net/npm/jquery@3.6.0/dist/jquery.min.js"></script>
<script>
    window.jQuery || document.write('<script src="~/lib/jquery/dist/jquery.min.js"><\/script>');
</script>

内容的提问来源于stack exchange，提问作者Waqas Akhtar