frontend Roadmap
前端 / Node.js 构建排障专题
前端 / Node.js 构建排障专题：聚合 EADDRINUSE 端口占用、pnpm install 失败、Vite/Nuxt 水合不匹配、CORS 跨域、CI 构建内存不足、JSON 解析错误和 Node 内存溢出等前端工程化问题的完整排障路径。
前端排障先区分浏览器运行时、构建期、SSR/水合、依赖安装和网络 API 五个层面，本地能跑不代表 CI 能跑，固定 Node/pnpm 版本和 frozen lockfile 是消除"本地好线上坏"的第一步。
Troubleshooting Path
推荐排障路线图
- 01
先区分问题发生在哪个阶段
是依赖安装失败、构建报错、SSR 水合不匹配还是运行时接口报错，不同阶段的排查工具和修复方向完全不同。
- 02
再对比本地和 CI 环境差异
Node 版本、包管理器、lockfile、CI 内存和 Docker socket 都可能导致本地通过但 CI 失败，用 frozen lockfile 确保依赖可复现。
- 03
继续检查 SSR 和浏览器兼容性
hydration mismatch 通常由时间、随机数、localStorage 或 window 条件渲染引起，浏览器专属逻辑应放 mounted 或 ClientOnly。
- 04
最后处理跨域和安全策略
CORS、Cookie SameSite、HTTPS 混合内容和缓存策略会让接口在 Postman 可用但浏览器失败，从 Network 面板读真实响应。
Common Issues
高频问题入口
Before You Change
执行前检查
- 固定 Node/pnpm 版本，CI 使用 frozen lockfile 确保依赖可复现
- 不要为了修 CORS 把所有来源和 Credential 同时放开，这会产生安全漏洞
- 不要随手删除 lockfile 解决 install 问题，会导致依赖版本不可控
- 新增 SSR 页面时检查 hydration warning，避免首屏闪烁
Start Here
优先阅读
JSON 解析失败常见原因与修复
JSON.parse 报 Unexpected token、SyntaxError 时，按行列号定位问题字符，检查是否有 trailing comma、单引号、// 注释、BOM 头或非 UTF-8 编码，用 jq、python -m json.tool 或 node 复现校验，标准 JSON 不支持注释与尾随逗号。
排障Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
排障Spring Boot 端口被占用怎么解决
Spring Boot 启动报 Web server failed to start: Port 8080 was already in use 时，Linux 用 lsof -iTCP:8080 -sTCP:LISTEN、Windows 用 netstat -ano | findstr :8080 找占用进程，判断是自身僵尸 Java 进程还是他人服务，再决定 kill 释放或通过 --server.port 换端口。
命令Base64 编码原理与使用场景
用 base64、base64 -d 和 Buffer.from().toString('base64') 编解码字符串，理解 Base64 用 64 个可打印字符表示二进制、编码后体积膨胀约 4/3，以及 URL Safe 变体把 + / 替换为 - _ 的用法，Base64 是编码不是加密。
Tools
相关工具
JSON 格式化与校验工具
在线格式化、压缩和校验 JSON 数据，支持 2 空格、4 空格和 Tab 缩进切换，精准定位解析错误的行号与位置，浏览器本地处理不上传数据，适合接口调试、日志分析与配置文件排查。
工具Base64 编码解码工具
支持 UTF-8 编码的 Base64 在线编码与解码工具，能正确处理中文、Emoji 与特殊字符，浏览器本地完成不上传数据，适合接口调试、JWT 拆解、图片 Data URL 和邮件附件转换等场景。
工具URL 编码解码工具
对 URL、查询参数和 form 表单值进行在线编码解码，区分 encodeURIComponent 与 encodeURI 的语义差异，正确处理中文、空格和保留字符，浏览器本地运行不上传数据，适合接口调试和路由排查。
工具时间戳转换工具
在 Unix 时间戳和可读日期之间双向转换，自动识别秒级和毫秒级精度，同时显示本地时区与 UTC 时间以及 ISO 8601 格式，适合排查日志时间线、Cookie 过期时间和接口时间戳差异问题。
工具UUID 生成器
批量在线生成 UUID v4 随机版本与 v7 时间戳排序版本，支持大小写切换、带/去横线格式，基于浏览器内置 crypto.getRandomValues 安全随机源，适合数据库主键、请求追踪 ID 与唯一标识生成。
工具Hash 哈希计算器
使用浏览器内置 Web Crypto API 计算文本的 SHA-1、SHA-256、SHA-384、SHA-512 哈希值，本地完成不上传数据，适合校验文件完整性、生成 API 签名、密码摘要和数据指纹等安全场景。
工具正则表达式测试器
在线测试正则表达式，支持全局/忽略大小写/多行/单行/Unicode 标志切换，实时高亮匹配结果并显示捕获组，内置常用正则模式（邮箱、IP、URL、日期等），浏览器本地执行不上传数据，适合接口调试、日志分析和文本提取场景。
工具JWT 解码器
在线解码 JWT（JSON Web Token），分别解析 Header 和 Payload 并格式化为可读 JSON，显示签名部分和过期时间，支持检测 alg 无签名风险和 exp 过期状态，浏览器本地解码不上传 Token，适合接口调试和认证排障场景。
Latest Updates
最近更新
All Runbooks
全部相关内容
CI 构建内存不足与进程被杀排查
CI 构建时出现 JavaScript heap out of memory、Killed 或 exit code 137，先区分 Node 堆内存不足与系统 OOM，再调整 NODE_OPTIONS=--max-old-space-size、Runner 内存和并发 job，覆盖 GitHub Actions、GitLab CI 和自建 Runner 场景。
排障CORS 预检 OPTIONS 请求失败排查
浏览器请求被 CORS 拦截、OPTIONS 预检返回 404/405 或缺少 Access-Control-Allow-Origin 头时，用 curl -X OPTIONS 复现预检，核对服务端允许的 Origin、Method、Headers 与 credentials 组合，注意带 Cookie 时不能用 * 通配。
排障JSON 解析失败常见原因与修复
JSON.parse 报 Unexpected token、SyntaxError 时，按行列号定位问题字符，检查是否有 trailing comma、单引号、// 注释、BOM 头或非 UTF-8 编码，用 jq、python -m json.tool 或 node 复现校验，标准 JSON 不支持注释与尾随逗号。
排障Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
排障pnpm install 失败排查：锁文件、代理和原生依赖
pnpm install 失败或 ERR_PNPM_OUTDATED_LOCKFILE 时，先区分失败发生在下载 registry、解析 pnpm-lock.yaml 还是 postinstall 原生编译阶段，检查 Node 版本、registry、HTTP_PROXY 组合，CI 用 --frozen-lockfile 复现，不要一上来就删 lockfile。
排障Spring Boot 端口被占用怎么解决
Spring Boot 启动报 Web server failed to start: Port 8080 was already in use 时，Linux 用 lsof -iTCP:8080 -sTCP:LISTEN、Windows 用 netstat -ano | findstr :8080 找占用进程，判断是自身僵尸 Java 进程还是他人服务，再决定 kill 释放或通过 --server.port 换端口。
排障Nuxt/Vue hydration mismatch 排查方法
Nuxt/Vue 生产构建出现 Hydration completed but contains mismatches 或首屏闪烁时，先用 build+preview 复现，检查是否 SSR 阶段使用了 Math.random、Date.now、localStorage、window 或按 viewport 输出不同 DOM，把浏览器专属逻辑放到 ClientOnly 或 mounted 之后。
命令Base64 编码原理与使用场景
用 base64、base64 -d 和 Buffer.from().toString('base64') 编解码字符串，理解 Base64 用 64 个可打印字符表示二进制、编码后体积膨胀约 4/3，以及 URL Safe 变体把 + / 替换为 - _ 的用法，Base64 是编码不是加密。
命令Java 查看线程堆栈命令
Java 生产环境抓线程堆栈的常用命令，jps -l 找 Java 进程 PID，jstack <pid> 打印线程栈、-l 附带锁信息，jcmd Thread.print 是 jstack 的替代，jstack 无响应时用 kill -3 触发 JVM dump 到 stdout，arthas thread 可在线不中断进程排查死锁。
命令Node/Nuxt 构建内存排查命令
Node/Nuxt/Next 构建报 JavaScript heap out of memory 或 exit code 137 时排查内存的常用命令，用 NODE_OPTIONS=--max-old-space-size=4096 扩大 V8 堆，du 查看 .nuxt/.output/.next 构建产物体积，free -h 与 dmesg 判断系统 OOM。
命令URL 编码中空格的 + 与 %20 区别
解释 URL 编码中空格何时是 + 何时是 %20，application/x-www-form-urlencoded 表单里空格编码为 +，RFC 3986 URI 规范里空格编码为 %20，JS 的 encodeURIComponent/encodeURI 都用 %20，URLSearchParams 构建 query 时会自动用 +。