Electron集成xterm.js对接pty时首行光标显示错乱问题

问题现象 #

对接xterm.js与node-pty实现web终端时，出现以下异常：

• 初始化阶段主动发送指令时，首行内容渲染错位：cd字符显示在终端最顶部，重复渲染指令内容，powershell提示符位置偏移
• 初始化后首行手动输入指令同样存在错位问题
• 首行渲染完成后，后续所有输入输出、光标位置均正常，无复现

相关实现代码 #

前端xterm组件代码 #

import { useEffect } from "react";
import { Terminal as TerminalType } from 'xterm';
import { FitAddon } from 'xterm-addon-fit';
import 'xterm/css/xterm.css';

export const Terminal = ({
    initialValue
  } : {
    initialValue?: string
  }) => {

  const id = 'xterm-container';
  useEffect(() => {
    const terminal = new TerminalType({
      cursorBlink: true,
      cursorStyle: window.api.isWindows ? "bar" : "underline"
    });

    const fitAddon = new FitAddon();
    terminal.loadAddon(fitAddon);

    window.api.receive('terminal.incomingData', (data) => {
      terminal.write(data);
    });
    
    terminal.open(document.getElementById(id) as HTMLElement);
    terminal.onData(key => {
      window.api.send('terminal.keystroke', key);
    });
    
    terminal.focus();
    window.api.send('terminal.keystroke', "cd C:\\\r\n");

  }, []);

  return (
    <div id={id}></div>
  )
}

后端PTY对接代码 #

ipcMain.on('terminal.keystroke', (_, key) => {
  ptyProcess.write(key);
});

const shell = isWindows ? 'powershell.exe' : 'bash';
ptyProcess = spawn(shell, [], {
  name: 'xterm-color',
  cols: 80,
  rows: 30,
  cwd: isWindows ? process.env.USERPROFILE : process.env.HOME,
  env: process.env as INonUndefinedEnv
});
ptyProcess.onData(data =>
  EnforceNonNull(win).webContents.send('terminal.incomingData', data)
);

问题根因 #

1. 时序竞争问题：terminal.open()执行后立刻发送初始化指令，此时xterm尚未完成首帧渲染，后端powershell也未完成初始化、未输出完首屏提示符与控制序列，提前写入的指令字符插入到shell初始化输出的ANSI控制序列流中，破坏了光标定位的上下文，导致渲染错位。
2. 两端尺寸不匹配：后端PTY初始化时写死了80列、30行，但前端使用FitAddon自适应容器尺寸，首次渲染后实际行列数与PTY预设值不一致，shell按照错误的宽度计算换行、光标位置，直接导致首行渲染错位。
3. 终端类型兼容性问题：PTY配置的终端类型为xterm-color，属于老旧的终端标准，对现代ANSI转义序列（尤其是Windows Powershell输出的光标控制序列）支持不全，部分控制序列解析异常。

修复方案 #

1. 调整初始化执行顺序，等首帧渲染、尺寸同步完成后再发送初始化指令：
   • terminal.open()后等待shell初始提示符输出完成
   • 调用fitAddon.fit()获取前端实际行列数，通知后端调用ptyProcess.resize()同步PTY尺寸
   • 尺寸同步完成、shell重绘提示符后，再发送需要自动执行的初始化指令
2. 监听终端尺寸变化事件，实时同步前后端行列数，避免尺寸不一致导致的渲染错误
3. 将PTY的终端类型从xterm-color改为xterm-256color，兼容现代shell的控制序列输出

修复后关键代码 #

前端调整部分：

useEffect(() => {
  const terminal = new TerminalType({
    cursorBlink: true,
    cursorStyle: window.api.isWindows ? "bar" : "underline"
  });
  const fitAddon = new FitAddon();
  terminal.loadAddon(fitAddon);
  let initFinished = false;

  window.api.receive('terminal.incomingData', (data) => {
    terminal.write(data);
    // 首次收到数据后等待初始化完成，同步尺寸再发指令
    if (!initFinished) {
      setTimeout(() => {
        fitAddon.fit();
        // 同步尺寸到后端
        window.api.send('terminal.resize', {
          cols: terminal.cols,
          rows: terminal.rows
        });
        // 等待提示符重绘完成后发送初始化命令
        setTimeout(() => {
          window.api.send('terminal.keystroke', "cd C:\\\r\n");
          initFinished = true;
        }, 300);
      }, 400);
    }
  });
    
  terminal.open(document.getElementById(id) as HTMLElement);
  terminal.onData(key => {
    window.api.send('terminal.keystroke', key);
  });
  // 监听后续尺寸变化实时同步
  terminal.onResize(({ cols, rows }) => {
    window.api.send('terminal.resize', { cols, rows });
  });
  terminal.focus();
}, []);

后端调整部分：

// 新增resize事件处理
ipcMain.on('terminal.resize', (_, { cols, rows }) => {
  ptyProcess.resize(cols, rows);
});

const shell = isWindows ? 'powershell.exe' : 'bash';
ptyProcess = spawn(shell, [], {
  name: 'xterm-256color', // 替换为兼容性更好的终端类型
  cols: 80,
  rows: 30,
  cwd: isWindows ? process.env.USERPROFILE : process.env.HOME,
  env: process.env as INonUndefinedEnv
});
ptyProcess.onData(data =>
  EnforceNonNull(win).webContents.send('terminal.incomingData', data)
);

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