vscode-extension-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VS Code Extension Guide

VS Code 扩展开发指南

Create, develop, and publish VS Code extensions.

创建、开发并发布VS Code扩展。

When to Use

适用场景

VS Code extension, extension development, vscode plugin
Creating a new VS Code extension from scratch
Adding commands, keybindings, or settings to an extension
Publishing to VS Code Marketplace

VS Code extension, extension development, vscode plugin
从零开始创建新的VS Code扩展
为扩展添加命令、快捷键绑定或设置
发布至VS Code Marketplace

Quick Start

快速开始

bash

undefined

bash

undefined

Scaffold new extension (recommended)

npm install -g yo generator-code yo code

Or minimal manual setup

mkdir my-extension && cd my-extension npm init -y && npm install -D typescript @types/vscode

undefined

mkdir my-extension && cd my-extension npm init -y && npm install -D typescript @types/vscode

undefined

Project Structure

项目结构

my-extension/
├── package.json          # Extension manifest (CRITICAL)
├── src/extension.ts      # Entry point
├── out/                  # Compiled JS (gitignore)
├── images/icon.png       # 128x128 PNG for Marketplace
└── .vscodeignore         # Exclude files from VSIX

my-extension/
├── package.json          # Extension manifest (CRITICAL)
├── src/extension.ts      # Entry point
├── out/                  # Compiled JS (gitignore)
├── images/icon.png       # 128x128 PNG for Marketplace
└── .vscodeignore         # Exclude files from VSIX

Building & Packaging

构建与打包

bash

npm run compile      # Build once
npm run watch        # Watch mode (F5 to launch debug)
npx @vscode/vsce package   # Creates .vsix

bash

npm run compile      # Build once
npm run watch        # Watch mode (F5 to launch debug)
npx @vscode/vsce package   # Creates .vsix

Done Criteria

完成标准

Extension activates without errors
All commands registered and working
Package size < 5MB (use
```
.vscodeignore
```
)
README.md includes Marketplace/GitHub links

扩展可正常激活且无错误
所有命令已注册并可正常工作
包大小小于5MB（使用
```
.vscodeignore
```
文件）
README.md包含Marketplace/GitHub链接

Quick Troubleshooting

快速排查问题

Symptom	Fix
Extension not loading	Add `activationEvents` to package.json
Command not found	Match command ID in package.json/code
Shortcut not working	Remove `when` clause, check conflicts

Topic	Reference
AI Customization	references/ai-customization.md
Code Review Prompts	references/code-review-prompts.md
Code Samples	references/code-samples.md
TreeView	references/treeview.md
Webview	references/webview.md
Testing	references/testing.md
Publishing	references/publishing.md
Troubleshooting	references/troubleshooting.md

症状	解决方法
扩展无法加载	在package.json中添加 `activationEvents`
命令找不到	确保package.json与代码中的命令ID一致
快捷键无法工作	移除 `when` 条件，检查冲突

主题	参考链接
AI定制化	references/ai-customization.md
代码审查提示	references/code-review-prompts.md
代码示例	references/code-samples.md
TreeView	references/treeview.md
Webview	references/webview.md
扩展测试	references/testing.md
扩展发布	references/publishing.md
问题排查	references/troubleshooting.md

Best Practices

最佳实践

命名の一貫性

命名一致性

公開前にパッケージ名・設定キー・コマンド名を統一：

項目	例
パッケージ名	`copilot-scheduler`
設定キー	`copilotScheduler.enabled`
コマンドID	`copilotScheduler.createTask`
ビューID	`copilotSchedulerTasks`

公开发布前统一包名、配置键、命令名：

项目	示例
包名	`copilot-scheduler`
配置键	`copilotScheduler.enabled`
命令ID	`copilotScheduler.createTask`
视图ID	`copilotSchedulerTasks`

通知の一元管理

通知统一管理

typescript

type NotificationMode = "sound" | "silentToast" | "silentStatus";

function getNotificationMode(): NotificationMode {
  const config = vscode.workspace.getConfiguration("myExtension");
  return config.get<NotificationMode>("notificationMode", "sound");
}

function notifyInfo(message: string, timeoutMs = 4000): void {
  const mode = getNotificationMode();
  switch (mode) {
    case "silentStatus":
      vscode.window.setStatusBarMessage(message, timeoutMs);
      break;
    case "silentToast":
      void vscode.window.withProgress(
        { location: vscode.ProgressLocation.Notification, title: message },
        async () => {},
      );
      break;
    default:
      void vscode.window.showInformationMessage(message);
  }
}

function notifyError(message: string, timeoutMs = 6000): void {
  const mode = getNotificationMode();
  if (mode === "silentStatus") {
    vscode.window.setStatusBarMessage(`⚠ ${message}`, timeoutMs);
    console.error(message);
    return;
  }
  void vscode.window.showErrorMessage(message);
}

設定で

notificationMode

を選べるようにすることで、ユーザーが通知音を制御可能。

typescript

type NotificationMode = "sound" | "silentToast" | "silentStatus";

function getNotificationMode(): NotificationMode {
  const config = vscode.workspace.getConfiguration("myExtension");
  return config.get<NotificationMode>("notificationMode", "sound");
}

function notifyInfo(message: string, timeoutMs = 4000): void {
  const mode = getNotificationMode();
  switch (mode) {
    case "silentStatus":
      vscode.window.setStatusBarMessage(message, timeoutMs);
      break;
    case "silentToast":
      void vscode.window.withProgress(
        { location: vscode.ProgressLocation.Notification, title: message },
        async () => {},
      );
      break;
    default:
      void vscode.window.showInformationMessage(message);
  }
}

function notifyError(message: string, timeoutMs = 6000): void {
  const mode = getNotificationMode();
  if (mode === "silentStatus") {
    vscode.window.setStatusBarMessage(`⚠ ${message}`, timeoutMs);
    console.error(message);
    return;
  }
  void vscode.window.showErrorMessage(message);
}

通过配置让用户可以选择

notificationMode

，从而控制通知音效。