Blazor项目注入JS文件报WebSocket、电路启动失败错误如何解决

问题场景 #

项目使用_layout.cshtml作为主布局文件，脚本引入代码如下：

<script src="_framework/blazor.server.js"></script>
<script src="js/app.js"></script>

站点运行时固定抛出3个错误：

Connection disconnected with error 'WebSocket is not in the OPEN state'
WebSocket is not in the OPEN state
Failed to start the circuit.

异常特征非常明确：

• app.js为新建文件时，站点首次运行可正常启动
• app.js替换为项目内已存在的存量文件时，站点直接加载失败

排查路径 #

按优先级从高到低依次排查：

• 脚本加载顺序错误：Blazor Server 初始化逻辑对加载时序敏感，blazor.server.js默认自动启动，若后续加载的自定义脚本存在阻塞、报错、全局变量修改，会直接打断circuit（电路）初始化流程，新建文件因为没有业务逻辑不会触发阻塞，所以能正常运行
• 全局API被污染：检查存量app.js是否存在重写window.WebSocket、window.fetch、window.EventSource等浏览器原生API的逻辑，Blazor Server依赖原生WebSocket建立SignalR连接，只要原生API被mock、拦截、重写，就会抛出WebSocket状态异常错误
• 文件编码异常：存量app.js如果带UTF-8 BOM头、编码为GBK/GB2312，或者文件开头存在不可见控制字符，会导致JS解析异常，打断Blazor启动时序；新建JS文件默认为无BOM的UTF-8编码，不会触发该问题
• 顶层执行阻塞/报错：存量文件如果顶层存在死循环、同步大计算逻辑、未捕获的抛出异常，会阻塞JS主线程，导致Blazor无法在超时窗口内完成WebSocket握手，直接触发circuit启动失败
• 静态文件配置错误：存量app.js如果生成操作被设置为“嵌入的资源”而非“内容”，或者路由权限规则拦截了/js/app.js的请求，会导致脚本加载返回404/401状态码；新建JS文件默认会配置正确的生成操作属性，不会出现该问题
• 互操作调用时机错误：存量app.js如果在顶层直接调用DotNet.invokeMethodAsync等Blazor JS互操作方法，会因为Blazor runtime未初始化完成直接报错，打断启动流程

修复方案 #

对应排查点逐一修复即可：

1. 调整脚本加载顺序，将所有自定义脚本放到blazor.server.js之前加载，避免Blazor启动后被后续脚本加载打断：

<script src="js/app.js"></script>
<script src="_framework/blazor.server.js"></script>

2. 移除app.js中重写浏览器原生通信API的逻辑，确有拦截需求的，添加路径判断规则，跳过/_blazor开头的Blazor内部通信请求
3. 将存量app.js转码为无BOM的UTF-8格式，删除文件开头的不可见控制字符
4. 将app.js顶层的同步重逻辑、可能抛出异常的逻辑移到DOMContentLoaded事件回调中执行，顶层添加全局错误捕获，避免未捕获异常中断整体JS执行
5. 右键点击项目中的app.js文件打开属性面板，将“生成操作”设置为“内容”，“复制到输出目录”设置为“如果较新则复制”，同时检查静态文件中间件、权限规则，确保/js/app.js路径可匿名正常访问
6. 如果app.js依赖Blazor互操作能力，关闭blazor自动启动，等所有自定义脚本加载完成后手动启动Blazor，启动完成后再执行业务初始化逻辑：

<!-- 关闭自动启动 -->
<script src="_framework/blazor.server.js" autostart="false"></script>
<script src="js/app.js"></script>
<script>
  blazor.start().then(() => {
    // 所有依赖Blazor环境的业务逻辑放到此处执行
    window.initApp && window.initApp();
  });
</script>

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