VSCode扩展onDidChangeTextDocument监听是否依赖用户激活窗口启动？

核心原因 #

vscode.workspace.onDidChangeTextDocument 是 VS Code 针对已加载到内存的文本文档的事件监听API，默认只有用户主动打开过的文件才会被加载为文本文档实例，未打开的文件变更不会触发该事件，这是API的原生设计限制，和async逻辑无关。

解决方案 #

改用 vscode.workspace.createFileSystemWatcher API，它直接监听文件系统层面的变更，不需要文件被用户打开，完全适配你的需求，同时修正你的代码里的重复注册监听器的问题。

修正后代码示例 #

import * as vscode from 'vscode';
import * as path from 'path';
import * as fs from 'fs/promises';

let toggle = false;
// 持久化保存watcher实例避免被垃圾回收
let metricsWatcher: vscode.FileSystemWatcher | null = null;

export async function activate(context: vscode.ExtensionContext) {
    console.log('Congratulations, your extension "Next Step" is now active!');
    setupExtension();
    const output = vscode.window.createOutputChannel('METRICS');

    if (!vscode.workspace.workspaceFolders) {
        return;
    }
    const rootFolderUri = vscode.workspace.workspaceFolders[0].uri;
    // 用Uri.joinPath拼接路径，跨系统兼容性更好
    const metricsFileUri = vscode.Uri.joinPath(rootFolderUri, 'metrics.json');

    const generateMetrics = vscode.commands.registerCommand(
        'extension.generateMetrics',
        async () => {
            console.log('Succesfully entered registerCommand');
            toggle = true;

            // 已有监听器则先销毁，避免重复注册
            if (metricsWatcher) {
                metricsWatcher.dispose();
            }

            // 创建文件系统监听器，仅监听根目录下的metrics.json
            metricsWatcher = vscode.workspace.createFileSystemWatcher(
                new vscode.RelativePattern(rootFolderUri, 'metrics.json')
            );

            // 监听文件变更事件
            metricsWatcher.onDidChange(async () => {
                if (!toggle) return;
                console.log('Succesfully captured metrics.json update');
                try {
                    // 直接读取文件内容，不需要依赖openTextDocument
                    const metricData = await fs.readFile(metricsFileUri.fsPath, 'utf-8');
                    // 此处填写你的后续业务逻辑
                    output.appendLine(metricData);
                } catch (err) {
                    console.error('读取metrics.json失败：', err);
                }
            });

            // 可选：监听文件首次生成事件
            metricsWatcher.onDidCreate(async () => {
                console.log('metrics.json has been created');
                // 同上填写对应业务逻辑
            });

            // 将watcher加入订阅列表，扩展卸载时自动销毁
            context.subscriptions.push(metricsWatcher);
        }
    );

    context.subscriptions.push(generateMetrics);
}

export function deactivate() {
    if (metricsWatcher) {
        metricsWatcher.dispose();
    }
}

关键注意点 #

• 用 vscode.RelativePattern 匹配目标文件，比手动拼接路径的跨系统兼容性更好，支持Windows、macOS、Linux全平台
• createFileSystemWatcher 返回的监听实例必须持久化存储，否则会被垃圾回收导致监听意外失效
• 可以根据业务需求选择监听onDidChange（变更）、onDidCreate（创建）、onDidDelete（删除）三类事件

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