Nuxt 4 启用 nuxt-security 后 socket.io 无法连接 localhost
数据小陈
结论
先不用急着换 Socket.IO 版本。这个现象更像是 Nuxt 4 项目里的 nuxt-security 在 Socket.IO 握手阶段拦截了请求:Socket.IO 客户端默认会先发 HTTP polling 请求,常见路径是 /socket.io/,并带有 EIO=4&transport=polling。如果 xss protection/XSS Validator 扫描并拒绝这类请求,客户端就会一直连不上 localhost。干净项目里没有 nuxt-security,所以能正常连接。
排查方式
- 打开浏览器 DevTools 的 Network,过滤
socket.io,确认/socket.io/?EIO=4&transport=polling是否返回 400、403,或者请求直接失败。 - 看 Console 有没有 CSP 相关报错。nuxt-security 除了 xss protection,也可能通过安全响应头限制
connect-src,让浏览器拦下 WebSocket。 - 在本地临时关闭 XSS 校验做对照。关闭后 Socket.IO 如果马上能连,基本可以确认是安全中间件配置的问题。不同版本的 nuxt-security 配置项名称可能略有差异,以项目安装的版本为准。
// nuxt.config.ts:仅用于本地定位,不建议生产环境长期全局关闭
export default defineNuxtConfig({
modules: ['nuxt-security'],
security: {
xssValidator: false
}
})
解决步骤
确认是 XSS 校验拦截后,先考虑放行 Socket.IO 路径,不要一上来就把安全模块全局关掉。
如果当前 nuxt-security 版本支持给 xssValidator 配置白名单,可以把 Socket.IO 的路径加进去。下面是一个示例,具体字段名要按安装版本调整:
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-security'],
security: {
xssValidator: {
// 仅在你的 nuxt-security 版本支持该白名单写法时使用
whiteList: ['/socket.io']
}
}
})
如果你的版本不支持路径白名单,可以在服务端中间件里跳过 /socket.io 前缀的请求,或者升级/降级到支持该配置的版本再处理。这里只需要让 Socket.IO 的握手和轮询请求通过,其他请求仍然保留 XSS 校验。
如果 Socket.IO 服务不在同一个 origin,比如客户端在 http://localhost:3000,Socket.IO 服务在 http://localhost:3001,还要确认服务端 CORS 和客户端连接地址一致:
// server.ts:Socket.IO 服务端
import { createServer } from 'node:http'
import { Server } from 'socket.io'
const httpServer = createServer()
const io = new Server(httpServer, {
cors: {
origin: 'http://localhost:3000',
credentials: true
}
})
httpServer.listen(3001)
// 客户端
import { io } from 'socket.io-client'
const socket = io('http://localhost:3001', {
withCredentials: true
})
如果 Network 里没有发出请求,而 Console 报 CSP 拦截,就需要把 Socket.IO 的 HTTP 和 WebSocket 地址加入 connect-src。字段写法同样按 nuxt-security 版本文档调整。
注意事项
- 不要把
xssValidator: false当作生产环境的最终方案,它会关掉整个项目的 XSS 校验。 - 使用
credentials: true或withCredentials: true时,CORS 的origin不能写成*,必须写明确的来源。 - 检查 Socket.IO 客户端和服务端的路径是否一致;如果服务端设置了
path,客户端也要同步设置。 - 如果问题只在开发环境出现,优先检查
localhost、端口以及 CSP 里的ws://、http://是否和实际地址完全一致。
备注:内容仅供参考。
