附录 E：常见问题

本附录解答 VSDB 开发和使用中的常见问题。

E.1 开发问题

Q: Worker 启动后立即退出

原因：Worker 脚本路径错误或未正确编译。

解决方案：

确保 npm run compile 已执行
检查 worker.js 是否存在于 dist/ 目录
检查 IpcManager 的 workerScriptPath 配置

const workerPath = vscode.extensions.getExtension('vsdb.vsdb')?.extensionPath
  ? path.join(extensionPath, 'dist', 'worker.js')
  : path.join(__dirname, 'worker.js');

Q: IPC 消息无响应

原因：Worker 未就绪或请求超时。

解决方案：

使用 waitReady() 等待 Worker 就绪
检查超时配置是否合理
检查 Worker 日志是否有错误

ipcManager.start();
await ipcManager.waitReady(5000);
const response = await ipcManager.sendRequest({ ... });

Q: Webview 无法接收消息

原因：Webview 未正确初始化或消息监听未设置。

解决方案：

确保 Webview 启用了 enableScripts
确保 React 组件正确监听 window.message

// extension 端
panel.webview.postMessage({ type: 'connections', payload: [...] });

// React 端
window.addEventListener('message', (event) => {
  handleExtensionMessage(event.data);
});

Q: Monaco Editor 加载缓慢

原因：Monaco 从 CDN 加载需要网络。

解决方案：

使用本地 Monaco 资源
或配置 CDN 加载路径

loader.config({
  paths: {
    vs: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.50.0/min/vs'
  }
});

E.2 连接问题

Q: 连接数据库失败

常见原因：

数据库服务未启动
网络不通或防火墙阻止
用户名/密码错误
端口配置错误

排查步骤：

检查数据库服务是否运行
使用 telnet host port 测试网络
检查连接配置是否正确
查看 VSDB 输出通道日志

Q: MySQL 连接超时

解决方案：

增加 connectTimeout 配置
检查 MySQL 是否允许远程连接
检查防火墙规则

await mysql.createConnection({
  host: config.host,
  connectTimeout: 20000,  // 20 秒
});

Q: PostgreSQL SSL 连接失败

解决方案：

配置 SSL 选项
或禁用 SSL（仅开发环境）

const pool = new Pool({
  host: config.host,
  ssl: config.ssl || false,  // 开发环境可禁用
});

E.3 性能问题

Q: 大数据查询卡顿

解决方案：

使用流式查询 streamQuery
前端使用虚拟滚动
添加 LIMIT 限制

// 使用流式查询
await ipcManager.sendRequest({
  type: 'streamQuery',
  payload: { sql: 'SELECT * FROM large_table' },
});

// 前端虚拟滚动
<FixedSizeList height={400} itemCount={rows.length} itemSize={35}>
  {Row}
</FixedSizeList>

Q: TreeView 展开缓慢

原因：每次展开都查询 Schema。

解决方案：

使用 Schema 缓存
预加载常用节点

// 缓存 Schema
const cached = schemaCache.get(connectionId);
if (cached) {
  return cached.tables;
}

E.4 扩展问题

Q: 扩展激活失败

常见原因：

VSCode 版本不满足
依赖未安装
入口文件路径错误

排查步骤：

检查 engines.vscode 配置
执行 npm install
检查 main 配置路径

{
  "engines": { "vscode": "^1.85.0" },
  "main": "./dist/extension.js"
}

Q: 打包扩展体积过大

解决方案：

使用 .vscodeignore 排除不必要文件
避免打包测试文件
使用 webpack 优化

.vscodeignore:
__tests__/**
node_modules/@types/**
*.test.ts

E.5 测试问题

Q: 测试数据库连接失败

解决方案：

使用 Docker 启动测试数据库
或使用 mock 驱动

# docker-compose.yaml
services:
  mysql-test:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: test

Q: Vitest 测试超时

解决方案：

增加测试超时配置
或优化测试代码

// vitest.config.ts
test: {
  testTimeout: 30000,  // 30 秒
}

E.6 使用问题

Q: 扫描未发现连接

原因：

配置文件格式不正确
扫描深度限制
文件被跳过

解决方案：

检查配置文件语法
确保配置文件在项目根目录附近
检查 .env 文件命名

有效的文件名：
.env
.env.local
.env.development

无效的文件名：
.env.prod（不在标准列表）
.env.backup（扩展名不匹配）

Q: 密码无法保存

原因：SecretStorage API 问题。

解决方案：

确保 VSCode 版本 >= 1.85.0
检查 SecretStorage 权限

await context.secrets.store(`vsdb.password.${id}`, password);

Q: 查询历史丢失

原因：

全局状态未持久化
清理策略删除了历史

解决方案：

固定重要查询
检查 globalState 存储

// 固定查询防止被清理
historyManager.pin(historyId);

E.7 其他问题

Q: 如何调试 Worker

解决方案：

在 Worker 中添加日志
使用 VSCode Attach to Process

// worker.ts
console.log('[Worker] Request:', request);

Q: 如何添加新数据库支持

参考第十一章扩展开发。

Q: 如何贡献代码

Fork 项目
创建功能分支
提交 PR

git checkout -b feature/new-database
npm run test
npm run lint
git push origin feature/new-database

Keyboard shortcuts

VSDB 技术文档