应用场景

SFTP 插件适用于以下场景：

• 本地开发，远程调试：在本地编写代码，保存后自动同步到远程服务器，无需手动上传
• 快速部署：本地测试通过后，一键同步到生产环境服务器
• 多服务器管理：同时管理多个远程服务器，快速切换上传目标
• 团队协作：统一开发环境，确保代码在服务器端运行一致

安装插件

打开 VSCode，按下快捷键 Ctrl + Shift + X 打开扩展商店，搜索 sftp，找到名为 SFTP 的插件（作者：Natizyskunk），这是安装量最高、最受欢迎的 SFTP 插件。点击安装即可。

安装完成后，VSCode 会在侧边栏显示 SFTP 图标，表示插件已成功安装。

配置插件

生成配置文件

插件安装完成后，我们需要为当前项目创建配置文件。有两种方式：

方式一：使用命令面板

1. 按下快捷键 Ctrl + Shift + P 打开命令面板
2. 输入 SFTP: Config 并回车
3. VSCode 会在当前工作区的 .vscode 文件夹下自动生成 sftp.json 配置文件

方式二：右键菜单

1. 在 VSCode 资源管理器中，右键点击项目文件夹
2. 选择 SFTP: Config
3. 同样会生成 sftp.json 配置文件

基础配置示例

打开生成的 sftp.json 文件，你会看到一个默认的配置模板。下面是一个基础配置示例：

{
    "name": "我的服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "root",
    "password": "your_password",
    "remotePath": "/var/www/project",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false
}

完整配置示例

下面是一个包含更多选项的完整配置示例：

{
    "name": "生产环境服务器",
    "host": "192.168.1.100",
    "protocol": "sftp",
    "port": 22,
    "username": "deployer",
    "password": "your_password",
    "remotePath": "/home/deployer/project",
    "context": "./",
    "uploadOnSave": true,
    "useTempFile": false,
    "openSsh": false,
    "downloadOnOpen": false,
    "ignore": [
        ".vscode",
        ".git",
        ".DS_Store",
        "node_modules",
        "*.log",
        "*.tmp"
    ],
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    },
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    },
    "sshConfigPath": null,
    "concurrency": 4
}

配置参数详解

连接配置参数

认证方式参数

SFTP 插件支持三种认证方式：

1. 密码认证（最简单）

{
    "username": "root",
    "password": "your_password"
}

2. 密钥认证（推荐）

{
    "username": "root",
    "privateKeyPath": "C:\\Users\\YourName\\.ssh\\id_rsa",
    "passphrase": "密钥密码（如果有的话）"
}

密钥文件路径说明：

• Windows: C:\\Users\\YourName\\.ssh\\id_rsa 或 ~/.ssh/id_rsa
• Linux/Mac: ~/.ssh/id_rsa
• 支持 OpenSSH 格式和 PPK 格式的密钥

3. SSH Config 配置（高级）

如果你已经配置了 SSH config 文件，可以直接引用：

{
    "sshConfigPath": "~/.ssh/config",
    "host": "myserver"
}

对应的 SSH config 文件内容：

Host myserver
    HostName 192.168.1.100
    User deployer
    Port 22
    IdentityFile ~/.ssh/id_rsa

路径配置参数

路径配置说明：

假设本地项目结构如下：

project/
├── src/
│   ├── index.js
│   └── utils.js
├── tests/
└── .vscode/
    └── sftp.json

• 如果 context 为 "./" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/src/index.js
• 如果 context 为 "./src" 且 remotePath 为 "/var/www/project"，则 src/index.js 会上传到 /var/www/project/index.js

自动同步参数

最佳实践建议：

• 开发环境：设置 uploadOnSave: true，方便快速同步
• 生产环境：设置 uploadOnSave: false，避免误操作

忽略文件配置

ignore 参数用于指定哪些文件或文件夹不需要同步，支持 glob 模式：

{
    "ignore": [
        "**/.vscode/**",
        "**/.git/**",
        "**/.DS_Store",
        "**/node_modules/**",
        "**/*.log",
        "**/*.tmp",
        "**/dist/**",
        "**/coverage/**"
    ]
}

常用忽略模式：

• **/.git/**：忽略 Git 版本控制文件
• **/node_modules/**：忽略 Node.js 依赖包
• **/*.log：忽略所有日志文件
• **/dist/**：忽略构建输出目录

监听器配置（Watcher）

监听器可以监控文件变化并自动执行同步操作：

{
    "watcher": {
        "files": "**/*",
        "autoUpload": true,
        "autoDelete": false
    }
}

注意事项：

• autoDelete: true 可能导致误删除，请谨慎使用
• 监听器会持续运行，可能影响性能，建议按需启用

同步选项（Sync Option）

syncOption 用于配置手动同步时的行为：

{
    "syncOption": {
        "delete": false,
        "skipCreate": false,
        "ignoreExisting": false,
        "update": true
    }
}

性能优化参数

{
    "concurrency": 8,
    "connectTimeout": 15000,
    "keepalive": 5000
}

性能优化建议：

• 网络环境好时，可以增加 concurrency 提高上传速度
• 网络不稳定时，增加 connectTimeout 避免连接超时
• 频繁操作时，减小 keepalive 保持连接活跃

插件使用

常用操作

安装并配置好插件后，可以通过以下方式使用：

1. 上传文件或文件夹

方式一：右键菜单

• 在资源管理器中右键点击文件或文件夹
• 选择 Upload 上传到服务器

方式二：命令面板

• 按 Ctrl + Shift + P 打开命令面板
• 输入 SFTP: Upload 并选择相应的命令

2. 下载文件或文件夹

• 右键点击文件或文件夹
• 选择 Download 从服务器下载

3. 同步操作

同步本地到远程：

• 命令面板输入 SFTP: Sync Local -> Remote
• 将本地所有文件同步到服务器

同步远程到本地：

• 命令面板输入 SFTP: Sync Remote -> Local
• 将服务器文件同步到本地

双向同步：

• 命令面板输入 SFTP: Sync Both Directions
• 根据文件修改时间自动判断同步方向

4. 对比文件差异

• 右键点击文件
• 选择 Diff with Remote
• VSCode 会显示本地文件和远程文件的差异

5. 列出远程文件

• 命令面板输入 SFTP: List
• 可以浏览远程服务器的文件目录

完整命令列表

按 Ctrl + Shift + P 打开命令面板，输入 SFTP 可以看到所有可用命令：

多服务器配置

在实际开发中，我们可能需要同时管理开发环境、测试环境和生产环境多个服务器。SFTP 插件支持在一个配置文件中配置多个服务器。

配置多个服务器

在 sftp.json 中使用数组格式配置多个服务器：

[
    {
        "name": "开发环境",
        "host": "192.168.1.101",
        "port": 22,
        "username": "developer",
        "password": "dev_password",
        "protocol": "sftp",
        "remotePath": "/home/developer/project",
        "uploadOnSave": true,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "测试环境",
        "host": "192.168.1.102",
        "port": 22,
        "username": "tester",
        "password": "test_password",
        "protocol": "sftp",
        "remotePath": "/var/www/test",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**"
        ]
    },
    {
        "name": "生产环境",
        "host": "192.168.1.103",
        "port": 22,
        "username": "deployer",
        "privateKeyPath": "~/.ssh/production_key",
        "protocol": "sftp",
        "remotePath": "/var/www/production",
        "uploadOnSave": false,
        "ignore": [
            ".vscode/**",
            ".git/**",
            "node_modules/**",
            "*.log"
        ]
    }
]

切换服务器

配置多个服务器后，每次执行上传、下载等操作时，VSCode 会弹出选择框，让你选择目标服务器。

也可以通过命令面板 SFTP: List All 查看所有配置的服务器。

最佳实践

1. 安全配置建议

不要将密码明文写入配置文件：

方案一：使用环境变量

{
    "username": "${env.SFTP_USER}",
    "password": "${env.SFTP_PASSWORD}"
}

方案二：使用密钥认证（推荐）

{
    "username": "deployer",
    "privateKeyPath": "~/.ssh/id_rsa"
}

将配置文件加入 .gitignore：

.vscode/sftp.json

如果需要团队共享配置，可以创建一个 sftp.json.example 模板文件，将敏感信息替换为占位符：

{
    "name": "示例配置",
    "host": "your_server_ip",
    "username": "your_username",
    "password": "your_password",
    "remotePath": "/path/to/project"
}

2. 工作流建议

开发阶段：

{
    "uploadOnSave": true,
    "downloadOnOpen": false,
    "watcher": {
        "autoUpload": true
    }
}

部署阶段：

{
    "uploadOnSave": false,
    "syncOption": {
        "update": true,
        "delete": false
    }
}

3. 团队协作建议

为团队创建统一的配置模板：

{
    "name": "团队开发服务器",
    "host": "${env.DEV_SERVER}",
    "username": "${env.DEV_USER}",
    "password": "${env.DEV_PASSWORD}",
    "remotePath": "/home/${env.DEV_USER}/project",
    "uploadOnSave": true,
    "ignore": [
        ".vscode/**",
        ".git/**",
        ".env",
        "node_modules/**",
        "*.log"
    ]
}

团队成员在本地创建 .env 文件配置自己的环境变量即可。

4. 性能优化建议

对于大型项目，建议优化以下配置：

{
    "concurrency": 8,
    "ignore": [
        "node_modules/**",
        "dist/**",
        "build/**",
        ".git/**",
        "**/*.log"
    ],
    "syncOption": {
        "update": true
    }
}

常见问题

1. 连接超时

**问题：**上传文件时提示连接超时。

解决方案：

• 检查服务器 IP 和端口是否正确
• 检查防火墙是否开放对应端口
• 增加 connectTimeout 参数：

  {
      "connectTimeout": 30000
  }
  

2. 权限不足

**问题：**上传文件提示 Permission denied。

解决方案：

• 确认登录用户对目标目录有写权限
• 在服务器上执行：chmod 755 /target/path
• 或切换到有权限的用户

3. 密钥认证失败

**问题：**使用密钥登录时提示认证失败。

解决方案：

• 确认密钥文件路径正确
• 确认密钥文件权限：chmod 600 ~/.ssh/id_rsa
• 如果密钥有密码，需要配置 passphrase
• Windows 用户注意路径格式：C:\\Users\\Name\\.ssh\\id_rsa

4. 文件同步冲突

**问题：**本地和远程文件都被修改，不知道以哪个为准。

解决方案：

• 使用 Diff with Remote 对比差异
• 手动合并代码后再上传
• 使用版本控制工具如 Git 管理代码

5. 上传速度慢

**问题：**上传大量文件时速度很慢。

解决方案：

• 增加并发数："concurrency": 10
• 完善 ignore 配置，避免上传不必要的文件
• 使用 Sync Local -> Remote 而不是 Upload Folder

参考资料

• SFTP 插件官方文档
• SSH 密钥认证配置
• SFTP 协议介绍

注册微软开发者账号

如果已经有微软账号，直接登录即可，如果没有，需要注册一个微软账号。登录：https://login.live.com/。

登录https://aka.ms/SignupAzureDevOps，注册微软开发者账号。设置保存默认即可，自己设置也行，不太重要。

右上角创建Personal Access Token，用于登录vsce。

创建的Token名随意，但是Organization和Scopes需要选择正确的，否则会报错。

• Organization：All accessible organizations
• Scopes：Full access

创建成功后，会生成一个Token，需要保存好，后续会用到。Token只会显示一次，如果忘记了，需要重新创建。

注册VSCode Publisher

登录：https://aka.ms/vscode-create-publisher，填写姓名即可如“Dominic Zhang”，会自动生成一个唯一的ID，ID只能是数字字母下划线，所以会生成“DominicZhang”。需要记住这个ID，后续会用到。

vsce登录并发布插件

输入在注册微软开发者账号时生成的Token，登录vsce。

vsce login DominicZhang                        
 WARNING  Failed to open credential store. Falling back to storing secrets clear-text in: /home/nic/.vsce
https://marketplace.visualstudio.com/manage/publishers/
Personal Access Token for publisher 'DominicZhang': ****************************************************

The Personal Access Token verification succeeded for the publisher 'DominicZhang'.

打包插件：

vsce package

发布插件：

vsce publish

配置Windows

下载安装XMing，启动Xlaunch。

1. 选择MultiWindow
2. 设置Display number为10（可以自行设置，主要是需要和后面在WSL2中设置的变量保持一致）
3. 选择Start no client（Windows的XMing是被动等待接收图像数据，所以选择该项）
4. 一直下一页，其余保持默认，点击完成即可。

配置VSCode

安装RemoteX11插件，直接在插件中心搜索安装即可。

打开设置页面，搜索Remote x11，找到如下配置项，将Display Number配置为10

配置WSL2

安装xclock用于测试

sudo apt-get install xclock

设置环境变量

export DISPLAY=localhost:10.0
# 或者
export DISPLAY=:0

运行xclock查看结果

在 VSCode 中编辑 Markdown 文本，复制到思源笔记后，思源笔记无法转义为 Markdown 格式。会变成一个代码块，但是代码块内的内容并不是复制的内容。

比如上面这段话复制到思源笔记成了下图这样：

但是我需要的是能够转义为 Markdown 的阅读模式。

解决方法

问题的原因在于 VSCode 复制的文本是带格式的，而思源笔记默认的粘贴模式是纯文本模式，所以会出现上面的问题。

解决方法就是从 VSCode 复制的内容为纯文本，一种可以把文本复制到 txt 文件中，再复制，但是比较麻烦。

第二种方法是使用 VSCode 的插件 Copy Plain Text，搜索下载后，默认快捷键为 Ctrl+Alt+C，可以复制为纯文本。

再次粘贴到思源笔记中，就可以转义为 Markdown 格式了。

在使用 VSCode 的过程中，我们经常会安装一些插件来提高开发效率。但是，由于某些原因，我们可能无法直接访问 VSCode 的插件市场，这时候我们就需要离线安装插件了。

这里存在两种情况，一种是为本地的 VSCode 安装插件，另一种是为远程的 VSCode 安装插件。本文将分别介绍这两种情况下的离线安装方法。

远程 VSCode 也就是 VSCode 的Remote Development功能，可以通过 SSH、Docker、WSL 等方式远程连接到远程主机上的 VSCode。

方法一：使用已安装的插件目录

• 从已经安装插件的电脑上拷贝所有插件，路径一般为 C:\用户\用户名\.vscode\extensions
• 拷贝到离线安装的电脑上的 .vscode/extensions 文件夹下即可，重启 VScode 即可安装成功。

对于远程 VSCode 我们需要知道，插件不区分操作系统，所以我们可以在本地的 Windows 上的 VSCode 上安装插件，然后将插件目录压缩后整个拷贝到远程主机上即可。

远程主机上的插件目录一般在 ~/.vscode-server/extensions 下。将压缩的文件解药到这个目录下，重启 VSCode 即可。

方法二：下载离线安装包 vslx 安装

• 到 VScode 插件中心 搜索需要使用的插件名称

• 下载对应的拓展程序文件，下载的文件的后缀是.vslx

  

• VSCode 中安装

  

安装 REST Client 插件

在 VSCode 中，你可以通过以下步骤安装 REST Client 插件：

• 打开 VSCode；
• 点击左侧的插件图标（Ctrl+Shift+X）；
• 搜索“REST Client”插件；
• 点击“安装”按钮。
• 发送 HTTP 请求

使用 REST Client 插件发送 HTTP 请求非常简单。你只需要创建一个新的.rest文本文件，将请求信息放入其中，然后使用快捷键Ctrl + Alt + R 或者右键菜单的 Send Request 选项发送请求。

下面是一个简单的 GET 请求的例子：

GET https://jsonplaceholder.typicode.com/posts/1 HTTP/1.1

这个请求会获取 JSONPlaceholder API 中的一篇博客文章。

如果你想添加请求头或请求体，可以使用以下语法：

GET https://jsonplaceholder.typicode.com/posts/1 HTTP/1.1
Content-Type: application/json

{
  "title": "foo",
  "body": "bar",
  "userId": 1
}

这个请求会在请求头中添加 Content-Type 头，请求体中包含 JSON 数据。

查看响应

发送请求后，你可以在编辑器底部看到响应信息。如果你想查看响应头、响应体或状态码等详细信息，可以使用以下语法：

###
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit..."
}

在这个例子中，###用来分隔请求和响应，这样你就可以很方便地查看请求和响应的详细信息了。

变量

REST Client 插件还支持变量的使用。你可以使用${variable}语法来定义变量，然后在请求中使用它们。例如：

@host = https://jsonplaceholder.typicode.com

GET ${host}/posts/1 HTTP/1.1

在这个例子中，我们定义了一个名为 host 的变量，并在请求中使用它来指定 API 的基础 URL。

循环

如果你需要发送多个请求，REST Client 插件支持循环语法。例如：

@host = https://jsonplaceholder.typicode.com

@for(i,1,10){
    GET ${host}/posts/${i} HTTP/1.1
}

在这个例子中，我们使用@for 语法来发送 10 个 GET 请求，每个请求 URL 中的 i 变量从 1 到 10 依次递增。

条件语句

如果你需要根据条件发送请求，REST Client 插件也支持条件语句。例如：

@host = https://jsonplaceholder.typicode.com

@if(isDebug){
    GET ${host}/posts/1 HTTP/1.1
}else{
    GET ${host}/posts/2 HTTP/1.1
}

在这个例子中，我们使用@if 语法来判断是否为调试模式，如果是就发送一个请求，否则发送另一个请求。

导入环境变量

REST Client 插件支持从外部文件中导入环境变量。例如，你可以在.env 文件中定义变量：

host=https://jsonplaceholder.typicode.com
isDebug=true

然后在请求文件中使用@environment 语法来导入这些变量：

@environment .env

@if(isDebug){
    GET ${host}/posts/1 HTTP/1.1
}else{
    GET ${host}/posts/2 HTTP/1.1
}

在这个例子中，我们使用@environment 语法从.env 文件中导入环境变量，然后在请求文件中使用这些变量。

结论

REST Client 插件是一个非常好用的工具，能够帮助开发人员快速、方便地发送 HTTP 请求并查看响应。在本文中，我们介绍了 REST Client 的基本使用方法，包括发送请求、查看响应、使用变量、循环、条件语句和导入环境变量等。希望这篇文章能够帮助你更好地使用 REST Client 插件。

使用 VSCode 远程登录失败，报错：Failed to connect to the remote extension host server (Error: WebSocket close with status code 1006)。

解决方法

vim /etc/ssh/sshd_config

AllowTcpForwarding no

AllowAgentForwarding no

# 替换为

AllowTcpForwarding yes

AllowAgentForwarding yes

保存后重启 sshd 服务：

systemctl restart sshd

Markdown 中的表格，只要符合语法就能够正常渲染显示，但是符合语法但是 Markdown 源码却不一定易读。就如以下的这个表格，可以正常显示，但是源码在源文件中竖线不对齐，就阅读困难。

源码：

|诗名|作者|朝代|
|-|-|-|
|白头吟|卓文君|两汉|
|锦瑟|李商隐|唐代|
|登科后|孟郊|唐代|

显示效果：

我们可以手动将其竖线对齐，如下这样就易读许多：

| 诗名   | 作者   | 朝代 |
| ------ | ------ | ---- |
| 白头吟 | 卓文君 | 两汉 |
| 锦瑟   | 李商隐 | 唐代 |
| 登科后 | 孟郊   | 唐代 |

显示效果保持一致。但是如果一个字符一个字符去手动对齐效率太低，也不符合 Markdown 设计初衷。这就用到了额外的插件，能够辅助我们完成这个工作。

Markdown All in One

VSCode 插件中心搜索Markdown All in One安装。

安装完成后，使用时右击窗口选择Format Document with：

选择Markdown All in One即可自动对齐所有表格竖线：

常见问题

格式化文档后仍未对齐

这是由于表格中同时有中英文，而中英文字体不等宽导致的。如果对阅读要求不高，可以不用管，实际上已经格式化完成了。如果需要对齐，那么可以查看编码字体与阅读字体推荐这篇文章的中文等宽字体下载并安装，即可正常对齐。

Markdown 标记语言旨在易于阅读、编写和理解。它的灵活性既是优点也是缺点。语法众多，因此格式可能不一致。某些构造在所有解析器中都不能很好地工作，应该避免。CommonMark 规范标准化解析器。

Markdownlint 是一个用于 Node.js 的静态分析工具，有一个标准规范，用于强制执行 Markdown 文件的标准和一致性。

Markdownlint 插件使用

markdownlint提供了多种使用场景下的解决方案，如命令行，编辑器甚至 GitHub Action。因为我平时写 Markdown 文档都是使用 VSCode，所以介绍一下 VSCode 下的使用。其他编辑器包括 VIM，Sublime 也都支持，可以前往官网查阅方法。

VSCode 需要下载插件，Ctrl+Shift+X打开插件中心，搜索Markdownlint安装即可。

安装插件后打开 Markdown 文档，如果有不符合规范的语法将会警告标识。如，标题前后没有空行，将会标识：

提示违反了第 22 条规范，第 22 条规范的就是标题前后需要有空行隔开。

目前有 53 条规范，可以在markdownlint/Rules.md查看所有规范的内容。

当然这些规范也都可以自定义是否检查，比如第 24 条规定，文档内不可以有重复的标题，但是我就有重复标题的需求，那该如何关闭这个检查呢，Markdownlint 提供了配置的方式。

Ctrl+Shift+P打开运行窗口，输入 Markdownlint，找到Creat or open the markdownlint configuration file。

创建一个配置文件，并输入以下内容，表示关闭第 24 条规范的检查：

{
  "MD024": false,
}

这样文档中将不会有第 24 条规范的检查警告，其他检查同理。

Markdownlint 自定义规则

MD001 - Heading levels should only increment by one level at a time

标题等级一次只能增加一级，不能跨级。

原理：标题代表文档的结构，跳过时可能会造成混淆 - 特别是对于可访问性场景。

MD002 - First heading should be a top-level heading

文档的第一个标题必须是最高级的标题（标题等级 1 级到 6 级逐渐降低）

MD003 - Heading style

整篇文档需要采用一致的标题格式。

MD004 - Unordered list style

无序列表格式需要一致。

MD005 - Inconsistent indentation for list items at the same level

• 同一级的列表缩进必须一致
• 在有序列表中，前面的数字序号可以左对齐，也可以右对齐

MD006 - Consider starting bulleted lists at the beginning of the line

一级列表不能缩进。

如下为报错：

Some text

  * List item
  * List item

MD007 - Unordered list indentation

无序列表嵌套缩进时默认采用两个空格。

MD009 - Trailing spaces

行尾最多可以添加两个空格，超过会给出警告，两个空格正好可以用于换行。

MD010 - Hard tabs

不能使用 tab 键缩进，要使用空格。

原理：硬制表符通常由不同的编辑器以不一致的方式呈现，并且比空格更难处理。

MD011 - Reversed link syntax

当遇到看似链接的文本，但语法似乎已反转（[] 和 () 反转）时，将触发此规则。

MD012 - Multiple consecutive blank lines

文档中不能有连续的空行，在代码块中此规则不会生效。

MD013 - Line length

默认行的最大长度是 80，此规则对代码块、表格、标题也生效。

MD014 - Dollar signs used before commands without showing output

在代码块中，终端命令前不需要有美元符号 ($) 如果代码块中既有终端命令，也有命令的输出，则终端命令前可以有美元符号 ($)。

MD018 - No space after hash on atx style heading

在"atx"格式的标题中，#号和文字间需用一个空格隔开。

MD019 - Multiple spaces after hash on atx style heading

在"atx"格式的标题中，#号和文字间只能用一个空格隔开，不能有多余的空格。

MD020 - No space inside hashes on closed atx style heading

在"closed_atx"格式的标题中，文字和前后的#号之间需用一个空格隔开。

MD021 - Multiple spaces inside hashes on closed atx style heading

在"closed_atx"格式的标题中，文字和前后的#号之间只能用一个空格隔开，不能有多余的空格。

MD022 - Headings should be surrounded by blank lines

标题行的上下行必须都是空行。

MD023 - Headings must start at the beginning of the line

标题行不能缩进。

MD024 - Multiple headings with the same content

文档不能有内容重复的标题。

MD025 - Multiple top-level headings in the same document

同一文档只能有一个最高级的标题，默认是只能有一个 1 级标题。

MD026 - Trailing punctuation in heading

标题行末尾不能有以下标点符号。

MD027 - Multiple spaces after blockquote symbol

创建引用区块时，右尖括号 ( > ) 和文字之间有且只能有一个空格。

MD028 - Blank line inside blockquote

两个引用区块间不能仅用一个空行隔开或者同一引用区块中不能有空行，如果一行中没有内容，则这一行要用>开头。

MD029 - Ordered list item prefix

有序列表的前缀序号格式必须只用 1 或者从 1 开始的加 1 递增数字。

MD030 - Spaces after list markers

列表（有序、无序）的前缀符号和文字之间用 1 个空格隔开 在列表嵌套或者同一列表项中有多个段落时，无序列表缩进两个空格，有序列表缩进 3 个空格。

MD031 - Fenced code blocks should be surrounded by blank lines

单独的代码块前后需要用空行隔开（除非是在文档开头或末尾），否则有些解释器不会解释为代码块

MD032 - Lists should be surrounded by blank lines

列表（有序、无序）前后需要用空行隔开，否则有些解释器不会解释为列表。

列表的缩进必须一致。

MD033 - Inline HTML

文档中不允许使用 HTML 语句。

MD034 - Bare URL used

单纯的链接地址需要用尖括号 (<>) 包裹，否则有些解释器不会解释为链接。

MD035 - Horizontal rule style

创建水平线时整篇文档要统一 (consistent)，要和文档中第一次创建水平线使用的符号一致。

MD036 - Emphasis used instead of a heading

不能用加粗代替标题。

MD037 - Spaces inside emphasis markers

用于创建强调的符号和强调的的文字之间不能有空格。

MD038 - Spaces inside code span elements

当用单反引号创建代码段的时候，单反引号和它们之间的代码不能有空格 如果要把单反引号嵌入到代码段的首尾，创建代码段的单反引号和嵌入的单反引号间要有一个空格隔开。

MD039 - Spaces inside link text

链接名和包围它的中括号之间不能有空格，但链接名中间可以有空格。

MD040 - Fenced code blocks should have a language specified

单独的代码块（此处是指上下用三个反引号包围的代码块）应该指定代码块的编程语言，这一点有助于解释器对代码进行代码高亮。

MD041 - First line in a file should be a top-level heading

文档的第一个非空行应该是文档最高级的标题，默认是 1 级标题。

MD042 - No empty links

链接的地址不能为空。

MD043 - Required heading structure

要求标题遵循一定的结构，默认是没有规定的结构。

MD044 - Proper names should have the correct capitalization

指定一些名称，会检查它是否有正确的大写。

MD045 - Images should have alternate text (alt text)

图片链接必须包含描述文本（alt text）。

MD046 - Code block style

整篇文档采用一致的代码格式。

MD047 - Files should end with a single newline character

文档需用一个空行结尾。

MD048 - Code fence style

表示代码块的标记需要一直，可以是波浪号，也可以是点号。但是需要保持一致。

MD049 - Emphasis style should be consistent

强调符号需要一直，如斜体。

MD050 - Strong style should be consistent

加粗符号需要保持一致。

MD051 - Link fragments should be valid

锚点需要表示正确。

在写 MD 文档时为了追求美观，表格通常都是对齐的，这就需要字体必须等宽，但是写代码时等宽字体的因为很瘦小，不容易阅读，所以想要一个插件能够在多个字体直接快速切换。万能 VSCode 啥都有，插件中心就有一款专门切换字体的插件Font Switcher。直接搜索安装。

配置与使用

打开配置脚本settings.json，如果以前修改过字体，找到"editor.fontFamily"配置项，如果没有就直接添加。

这是我的字体，添加你们机器上安装的字体，每个逗号间隔都是不同的字体，可以使用Font Switcher切换，需要注意的是，字体名没有空格不需要加单引号，加了也无妨，如果有空格，一定要加引号。

"editor.fontFamily": "'Sarasa Mono SC', 微软雅黑，'Noto Sans Mono CJK SC', 'JetBrains Mono', Consolas, monospace",

Ctrl+Shift+P打开运行窗口，输入Switch Font，选择切换的字体。如图：


当有多个项目同时打开时，VSCode 窗口开得太多就找不到自己想要打开的窗口，因为窗口命名默认按照当前打开的文件命名的，不是很清楚。就需要挨个打开才能确定自己想要打开的窗口。

如果能按照项目名命名窗口就会便捷许多，好在 VSCode 提供重命名的方式。同样的需求可能在浏览器中也会遇到，可以参考浏览器任务栏多窗口命名 - 如云泊。

修改方式

File -> Preferences -> Setting 搜索 Window: Title 改成：

${dirty}${rootName}${separator}${activeEditorMedium}${separator}${appName}

其他可用配置说明：

"${activeEditorShort}": 文件名 (例如 myFile.txt)。
"${activeEditorMedium}": 相对于工作区文件夹的文件路径 (例如, myFolder/myFileFolder/myFile.txt)。
"${activeEditorLong}": 文件的完整路径 (例如 /Users/Development/myFolder/myFileFolder/myFile.txt)。
"${activeFolderShort}": 文件所在的文件夹名称 (例如, myFileFolder)。
"${activeFolderMedium}": 相对于工作区文件夹的、包含文件的文件夹的路径, (例如 myFolder/myFileFolder)。
"${activeFolderLong}": 文件所在文件夹的完整路径 (例如 /Users/Development/myFolder/myFileFolder)。
"${folderName}": 文件所在工作区文件夹的名称 (例如 myFolder)。
"${folderpath}": 文件所在工作区文件夹的路径 (例如 /Users/Development/myFolder)。
"${rootName}": 打开的工作区或文件夹的名称 (例如 myFolder 或 myWorkspace)。
"${rootPath}": 打开的工作区或文件夹的文件路径 (例如 /Users/Development/myWorkspace)。
"${appName}": 例如 VS Code。
“${remoteName}”: 例如 SSH
${dirty}: 表明活动编辑器具有未保存更改的时间的指示器。
"${separator}": 一种条件分隔符 ("-"), 仅在被包含值或静态文本的变量包围时显示

在VSCode使用搜索/替换时，匹配的字符会“高亮”（高亮个屁），知道自己当前搜到到什么位置，如果匹配字符较少还好，如果匹配太多，默认的高亮就很难发现当前已经搜索到什么位置了。比如我当前在搜索“搜索”这两个字：

大家还能看到我当前搜索到哪了吗？

但是如果设置成这样呢？

配置

搜索匹配时高亮颜色

添加如下配置：

    "workbench.colorCustomizations": {
        "editor.findMatchBackground": "#ff0000",
    }

表示搜索匹配时高亮，高亮颜色为红色。自己可以选择合适的颜色。

搜索结果高亮

与上面不同的是，搜索时会高亮所有的结果，但是点击箭头匹配到当前结果时就是上面的高亮，其余未匹配的状态就是下面的高亮：

"workbench.colorCustomizations": {
    "editor.findMatchHighlightBackground": "#ff00ff",
}

选择时颜色

    "workbench.colorCustomizations": {
        "editor.selectionBackground": "#2f00ff",
    }

范围搜索时背景颜色

有时候搜索不是全局搜索，是在自己选中的范围内搜索，那这个范围也是可以高亮的，开启范围搜索需要点击搜索框的按钮，如图所示：

"workbench.colorCustomizations": {
    "editor.findMatchHighlightBackground": "#ff00ff",
    "editor.findRangeHighlightBackground": "#ff9900"
}

可以通过配置服务端或客户端的 SSH 来保持 SSH 链接：

方法一：配置服务端

可以在服务端配置，让 server 每隔 30 秒向 client 发送一个 keep-alive 包来保持连接：

vim /etc/ssh/sshd_config

ClientAliveInterval 30
ClientAliveCountMax 60

第二行配置表示如果发送 keep-alive 包数量达到 60 次，客户端依然没有反应，则服务端 sshd 断开连接。如果什么都不操作，该配置可以让连接保持 30s*60，30 min

重启本地 ssh

sudo service ssh restart

如果找不到 ssh,”Failed to restart ssh.service: Unit ssh.service not found.” ，需要安装

sudo apt-get install openssh-server

方法二：配置客户端

如果服务端没有权限配置，或者无法配置，可以配置客户端 ssh，使客户端发起的所有会话都保持连接：

vim /etc/ssh/ssh_config

ServerAliveInterval 30
ServerAliveCountMax 60

本地 ssh 每隔 30s 向 server 端 sshd 发送 keep-alive 包，如果发送 60 次，server 无回应断开连接。

在 VSCode 里可以直接添加配置，效果一样：

Host 11.22.33.44
  HostName 11.22.33.44
  User user
  Port 112343
  ServerAliveInterval 30
  ServerAliveCountMax 60

"gitlens.menus": {
    "editorGroup": {
        "blame": false,
        "compare": true
    },
},

Windows 环境下，使用 VSCode 的终端时，中文显示为乱码，如使用git status命令查看修改文件时，中文文件名就无法正常显示：

探究原因

因为终端被替换成了 git bash，它对所有非英文的字符进行了转义。

官方文档提到：

输出路径的命令（例如ls-files、diff）将通过将路径名括在双引号中并以与 C 转义控制字符相同的方式用反斜杠转义这些字符来引用路径名中的异常字符（例如\t用于 TAB, \n 表示LF，\\表示反斜杠）或值大于 0x80 的字节（例如，八进制 \302\265 表示 UTF-8 中的“micro”）。如果此变量设置为 false，则高于 0x80 的字节不再被视为异常。无论此变量的设置如何，双引号、反斜杠和控制字符总是被转义。一个简单的空格字符不被认为是异常的。许多命令可以使用 -z 选项完全逐字输出路径名。默认值是 true。

解决方法

命令行输入，取消转义：

git config --global core.quotepath false

用惯了 Linux 终端的命令，Windows 的 shell 真的太不顺手了，但是 Gitbash 很多命令相似，可以将默认的 shell 换成 Gitbash。

打开settings.json配置文件，添加如下

    "terminal.integrated.profiles.windows": {
        "PowerShell -NoProfile": {
          "source": "PowerShell",
          "args": [
            "-NoProfile"
          ]
        },
        "Git-Bash": {
          "path": "D:\\Software\\Git\\bin\\bash.exe", //bin路径下的bash，不是git-bash.exe。否则会打开外部窗口
          "args": []
        }
      },
    "terminal.integrated.defaultProfile.windows": "Git-Bash",

修改终端配色

打开Base16 Terminal Colors for Visual Studio Code，选择一款配置复制

打开 VScodesettings.json，替换如下

 "workbench.colorCustomizations": {
        "terminal.background":"#1C2023",
        "terminal.foreground":"#C7CCD1",
        "terminalCursor.background":"#C7CCD1",
        "terminalCursor.foreground":"#C7CCD1",
        "terminal.ansiBlack":"#1C2023",
        "terminal.ansiBlue":"#AE95C7",
        "terminal.ansiBrightBlack":"#747C84",
        "terminal.ansiBrightBlue":"#AE95C7",
        "terminal.ansiBrightCyan":"#95AEC7",
        "terminal.ansiBrightGreen":"#95C7AE",
        "terminal.ansiBrightMagenta":"#C795AE",
        "terminal.ansiBrightRed":"#C7AE95",
        "terminal.ansiBrightWhite":"#F3F4F5",
        "terminal.ansiBrightYellow":"#AEC795",
        "terminal.ansiCyan":"#95AEC7",
        "terminal.ansiGreen":"#95C7AE",
        "terminal.ansiMagenta":"#C795AE",
        "terminal.ansiRed":"#C7AE95",
        "terminal.ansiWhite":"#C7CCD1",
        "terminal.ansiYellow":"#AEC795"
    },

修改后效果

修改终端字体

方法一：打开 VScodesettings.json，加上下面这个配置，字体改成自己电脑上的字体

    "terminal.integrated.fontFamily": "JetBrains Mono",

方法二：打开设置页面，搜索terminal font

修改后的效果

解决中文乱码

git config --global core.quotepath false

探究原因

本地记录的服务器信息和现有的产生了冲突

解决方法

方法一

将known_hosts文件的内容全部删除。

C:\Users\user name\.ssh\known_hosts

方法二

搜遍全网几乎都是上述方法，应该绝大部分人通过上述方法都能解决。如果你也跟我一样不走运，不管是重新生成公私钥，还是删除hnow_hosts都不行，那么可以尝试修改 VSCode 使用的ssh.exe。Windows 下默认使用的是环境变量里配置的OpenSSH提供的ssh.exe。你可以将环境变量里的OpenSSH删除。然后在VSCode设置里搜索remote，也就是设置插件remote ssh。

将 Path 强制设置成Git安装包内的ssh.exe

或者mobaxterm安装包内的ssh.exe

参考

Debug | VSCode | 过程试图写入的管道不存在 - CodeAntenna

VScode 通过 remote ssh 连接虚拟机 & 报错 过程试图写入的管道不存在（已解决）_Tasdily 的博客-CSDN 博客_vscode 过程试图写入的管道不存在

安装插件

打开插件中心，搜索sftp，安装量最高的就是我们需要的插件，点击安装。

配置插件

插件安装完成后，输入快捷键Control + Shift + P 弹出命令面板，然后输入sftp:config，回车，当前工程的.vscode文件夹下就会自动生成一个sftp.json文件，我们需要在这个文件里配置的内容可以是：

{
  "host": "192.168.xxx.xxx", //服务器 ip
  "port": 22,               //端口，sftp 模式是 22
  "username": "",           //用户名
  "password": "",           //密码
  "protocol": "ftp",       //模式，sfpt 或者 ftp
  "agent": null,
  "privateKeyPath": null,   //存放在本地的已配置好的用于登录工作站的密钥文件（也可以是 ppk 文件）
  "passphrase": null,
  "passive": false,
  "interactiveAuth": false,
  "remotePath": "/root/node/build/", //服务器上的文件地址
  "context": "./server/build",      //本地的文件地址
  "uploadOnSave": true,             //监听保存并上传
  "syncMode": "update",
  "watcher": {
    //监听外部文件
    "files": false,                 //外部文件的绝对路径
    "autoUpload": false,
    "autoDelete": false
  },
  "ignore": [
    //指定在使用 sftp: sync to remote 的时候忽略的文件及文件夹
    //注意每一行后面有逗号，最后一行没有逗号
    //忽略项
    "**/.vscode/**",
    "**/.git/**",
    "**/.DS_Store"
  ]
}

插件使用

• 可以直接右击文件，选择Upload，会将文件上传至配置好的remotePath。

• 可以Control + Shift + P输入sftp，选择想要执行的命令，命令都是字面意思，不多做解释。

  

• 如果有多个 IP 需要配置，可以在sftp.json文件中，通过方括号[]添加。比如

  [
      {
      "host": "192.168.xxx.01", //服务器 ip
      "port": 22,               //端口，sftp模式是22
      "username": "",           //用户名
      "password": "",           //密码
      "protocol": "sftp",       //模式，sfpt 或者 ftp
      "agent": null,
      },
      {
      "host": "192.168.xxx.02", //服务器 ip
      "port": 22,               //端口，sftp模式是22
      "username": "",           //用户名
      "password": "",           //密码
      "protocol": "sftp",       //模式，sfpt 或者 ftp
      "agent": null,
      },
      {
      "host": "192.168.xxx.03", //服务器 ip
      "port": 22,               //端口，sftp模式是22
      "username": "",           //用户名
      "password": "",           //密码
      "protocol": "sftp",       //模式，sfpt 或者 ftp
      "agent": null,
      }
  ]
  

Linux

sudo apt-get install clang-format

windows

每每到这时候就越能感受到用 Linux 作为开发环境的优势，Windows 安装就稍显复杂了。

1. 你可以选择安装完整的 LLVM，在bin目录可以看到clang-format.exe。安装完后，将 bin 目录添加到环境变量中。

2. 你也可以只下载clang-format.exe，从LLVM Snapshot Builds下载安装包。在下载页面的底部。同样你需要将单独下载的文件加入到环境变量中。

   

使用

入门使用

Linux 可以直接命令行，使用以 LLVM 代码风格格式化main.cpp, 结果直接写到main.cpp

clang g-format -i main.cpp -style=LLVM

进阶配置

如果每次编码都命令行执行一遍那也太麻烦了，而且每次修改也不止一个文件。最好的方式就是每次保存文件时自动格式化。比如 VSCode 已经内置了Clang-Format稍作配置即可实现，接下来介绍几种常见 IDE 如何配置Clang-Format。

VSCode

VSCode 最常用，因为内置了Clang-Format也最容易配置。

• 安装C/C++插件，Ctrl+Shift+X打开应用商店，搜索C/C++找到下图插件，安装后会自动安装Clang-Format程序，无需单独下载。默认安装路径为： C:\Users\(你的用户名)\.vscode\extensions\ms-vscode.cpptools-1.7.1\LLVM\bin\clang-format.exe。
  
• 打开设置页面（左下角齿轮 - 设置），搜索format，勾选Format On Save，每次保存文件时自动格式化文档。下方的设置是决定每次格式化是整个文档，还是做过修改的内容。默认是file，对整个文档进行格式化。
  
• 仍在设置页面搜索Clang，配置如下。.clang-format文件最后详解。
  
• 效果图
  

QtCreator

• 安装Beautifier插件：帮助（Help）-关于插件（About Plugins）- Beautifier勾选，重启 QtCreator。
  
• 工具（Tool）- Beautifier，配置如图。该配置，保存文档时自动格式化，并选择Clang-Format作为格式化工具。
  
  配置Clang-Format程序路径，如果开头已经apt install安装过，这里会自动补全。
  
• Use predefined style可以选择内置的一些代码风格，如LLVM，Google等。
• Use customized style使用自定义的一些代码风格。点击添加（Add）将配置文件粘贴进去即可，具体配置文件见最后。
• 别忘了点击OK保存。

Eclipse

• 安装cppstyle插件：Help - Eclipse Marketplace - 搜索cppstyle。

• 下载cpplint。 可以去github上下载cpplint的源码，下载完之后解压放到某个目录下。

• 在Window - Preferences - C/C++ - CppStyle页面把clang-format的路径添加进去，然后把cpplint的目录指向刚才下载的styleguide目录下的cpplint/cpplint.py就可以了。勾选下面的Enable cpplint，Run clang-format on file save，然后点击Apply and Close保存修改并退出。如下图所示。

  

• 此时再保存代码，将会出现如下错误，因为我们还未给当前项目编写配置文件.clang-format。将最后一章提到的配置文件放到当前项目的下即可，程序会自动搜索。

  Cannot find .clang-format or _clang-format configuration file under any level parent directories of path.
  Clang-format will default to Google style.
  

配置简介

上文多次提到了.clang-format配置文件，该文件决定了代码如何格式化，现在来介绍如何使用该文件。

导出.clang-format文件

如果重新编写一份配置文件，需要考虑的东西太多，clang-format内置了一些常见风格，我们可以根据已有的配置文件稍作修改，形成自己的代码风格。所以我们先导出一份内置的配置文件。

clang-format -style=可选格式名 -dump-config > .clang-format
# 可选格式最好写预设那那几个写最接近你想要的格式。比如我想要接近 Google C++ style 的。我就写-style=google

各个选项的含义

这里给出了配置的含义，感兴趣也可以查看官方文档，还提供了一些有案例，描述更清晰。

一些比较明显的代码分格区别

# 括号是分行，还是不分行，只有当 BreakBeforeBraces 设置为 Custom 时才有效
BraceWrapping:
  AfterCaseLabel:  true
  # class 定义后面
  AfterClass:      true
  # 控制语句后面
  AfterControlStatement: true
  AfterEnum:       true
  AfterFunction:   true
  AfterNamespace:  true
  AfterObjCDeclaration: true
  AfterStruct:     true
  AfterUnion:      true
  AfterExternBlock: true
  BeforeCatch:     true
  BeforeElse:      true
  # 缩进大括号，if else 语句后面的括号缩进
  IndentBraces:    false
  SplitEmptyFunction: true
  SplitEmptyRecord: true
  SplitEmptyNamespace: true
BreakBeforeBinaryOperators: None
BreakBeforeBraces: Custom

# tab 宽度
TabWidth: 4

# 换行缩进字符数
IndentWidth:     4

# 宏定义对齐
AlignConsecutiveMacros: AcrossEmptyLinesAndComments

基于LLVM代码风格修改的个人使用版本：

---
Language:        Cpp
# BasedOnStyle:  LLVM
AccessModifierOffset: -2
AlignAfterOpenBracket: Align
# 宏定义对齐
AlignConsecutiveMacros: AcrossEmptyLinesAndComments
AlignConsecutiveAssignments: true
AlignConsecutiveDeclarations: true
AlignConsecutiveBitFields: true
AlignEscapedNewlines: Right
AlignOperands:   true
AlignTrailingComments: true
AllowAllArgumentsOnNextLine: true
AllowAllConstructorInitializersOnNextLine: true
AllowAllParametersOfDeclarationOnNextLine: true
AllowShortBlocksOnASingleLine: Never
AllowShortCaseLabelsOnASingleLine: false
# 是否允许短方法单行，只有一行的函数将不会分行，直接写在函数名后
AllowShortFunctionsOnASingleLine: false
AllowShortLambdasOnASingleLine: All
AllowShortIfStatementsOnASingleLine: Never
AllowShortLoopsOnASingleLine: false
AlwaysBreakAfterDefinitionReturnType: None
AlwaysBreakAfterReturnType: None
AlwaysBreakBeforeMultilineStrings: false
AlwaysBreakTemplateDeclarations: MultiLine
BinPackArguments: true
BinPackParameters: true
# 括号是分行，还是不分行，只有当 BreakBeforeBraces 设置为 Custom 时才有效
BraceWrapping:
  AfterCaseLabel:  true
  # class 定义后面
  AfterClass:      true
  # 控制语句后面
  AfterControlStatement: true
  AfterEnum:       true
  AfterFunction:   true
  AfterNamespace:  true
  AfterObjCDeclaration: true
  AfterStruct:     true
  AfterUnion:      true
  AfterExternBlock: false
  BeforeCatch:     true
  BeforeElse:      true
  # 缩进大括号
  IndentBraces:    false
  SplitEmptyFunction: true
  SplitEmptyRecord: true
  SplitEmptyNamespace: true
BreakBeforeBinaryOperators: None
BreakBeforeBraces: Custom
BreakBeforeInheritanceComma: false
BreakInheritanceList: BeforeColon
BreakBeforeTernaryOperators: true
BreakConstructorInitializersBeforeComma: false
BreakConstructorInitializers: BeforeColon
BreakAfterJavaFieldAnnotations: false
BreakStringLiterals: true
ColumnLimit:     100
CommentPragmas:  '^ IWYU pragma:'
CompactNamespaces: false
ConstructorInitializerAllOnOneLineOrOnePerLine: false
ConstructorInitializerIndentWidth: 4
ContinuationIndentWidth: 4
Cpp11BracedListStyle: true
DeriveLineEnding: true
DerivePointerAlignment: false
DisableFormat:   false
ExperimentalAutoDetectBinPacking: false
FixNamespaceComments: true
ForEachMacros:
  - foreach
  - Q_FOREACH
  - BOOST_FOREACH
IncludeBlocks:   Preserve
IncludeCategories:
  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
    Priority:        2
    SortPriority:    0
  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
    Priority:        3
    SortPriority:    0
  - Regex:           '.*'
    Priority:        1
    SortPriority:    0
IncludeIsMainRegex: '(Test)?$'
IncludeIsMainSourceRegex: ''
IndentCaseLabels: false
IndentGotoLabels: true
IndentPPDirectives: None
# 换行缩进字符数
IndentWidth:     4
IndentWrappedFunctionNames: false
JavaScriptQuotes: Leave
JavaScriptWrapImports: true
KeepEmptyLinesAtTheStartOfBlocks: true
MacroBlockBegin: ''
MacroBlockEnd:   ''
MaxEmptyLinesToKeep: 1
NamespaceIndentation: None
ObjCBinPackProtocolList: Auto
ObjCBlockIndentWidth: 0
ObjCSpaceAfterProperty: false
ObjCSpaceBeforeProtocolList: true
PenaltyBreakAssignment: 2
PenaltyBreakBeforeFirstCallParameter: 19
PenaltyBreakComment: 300
PenaltyBreakFirstLessLess: 120
PenaltyBreakString: 1000
PenaltyBreakTemplateDeclaration: 10
PenaltyExcessCharacter: 1000000
PenaltyReturnTypeOnItsOwnLine: 60
PointerAlignment: Right
ReflowComments:  true
SortIncludes:    true
SortUsingDeclarations: true
SpaceAfterCStyleCast: false
SpaceAfterLogicalNot: false
SpaceAfterTemplateKeyword: true
SpaceBeforeAssignmentOperators: true
SpaceBeforeCpp11BracedList: false
SpaceBeforeCtorInitializerColon: true
SpaceBeforeInheritanceColon: true
SpaceBeforeParens: ControlStatements
SpaceBeforeRangeBasedForLoopColon: true
SpaceInEmptyBlock: false
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles:  false
SpacesInConditionalStatement: false
SpacesInContainerLiterals: true
SpacesInCStyleCastParentheses: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
SpaceBeforeSquareBrackets: false
Standard:        Latest
StatementMacros:
  - Q_UNUSED
  - QT_REQUIRE_VERSION
TabWidth:        8
UseCRLF:         false
UseTab:          Never
...

格式化最新的commit代码

clang-format还提供一个clang-format-diff.py脚本，用来格式化patch，code review提交代码前，跑一遍下面的代码。

// 格式化最新的 commit，并直接在原文件上修改
git diff -U0 HEAD^ | clang-format-diff.py -i -p1

常见问题

如何看懂官方文档并编写配置文件

官方文档里有各种设置的示例代码，即使不知道想要的格式化是哪个配置参数，翻一翻官方文档是示例大概率能找到。那么找到了想要的配置参数，如何在文件里配置呢？

以宏定义对齐为例。我们想要宏定义的值保持对齐的状态，如下一节图片所示。可以翻一遍官方文档，可以发现这个示例代码对应的参数可能是我们想要的，AlignConsecutiveMacros翻译为对齐连续的宏定义。那应该八九不离十了。

找到了参数如何编写配置文件呢？可以继续看这个参数下面的更多示例，每一个示例都对应一个配置可能值Possible values。

• ACS_None (in configuration: None) Do not align macro definitions on consecutive lines. ACS_None为这个配置的缩写，None表示在配置文件里的值。该配置表示不对宏定义进行对齐操作，在配置文件里可以添加如下：

  AlignConsecutiveMacros: None
  

• ACS_Consecutive (in configuration: Consecutive) Align macro definitions on consecutive lines. This will result in formattings like:

  #define SHORT_NAME       42
  #define LONGER_NAME      0x007f
  #define EVEN_LONGER_NAME (2)
  
  #define foo(x) (x * x)
  /* some comment */
  #define bar(y, z) (y + z)
  

  ACS_Consecutive为这个配置的缩写，Consecutive表示在配置文件里的值。该配置表示对连续的宏定义进行对齐，在配置文件里可以添加如下：

  AlignConsecutiveMacros: Consecutive
  

宏定义对齐失效

# 宏定义对齐
AlignConsecutiveMacros: AcrossEmptyLinesAndComments

使用宏定义对齐更详细的配置，可以参考官方文档。使用该配置一定要使用等宽的字体，否则配置生效但是显示不正确。 比如我是用微软雅黑字体作为编码字体，因为该字体每个字符不等宽，导致格式化正确，但是显示不正确。

如果将字体换位等宽字体如常用的Consolas，就可以正常显示。

通常函数的注释一般都比较长，而且每个函数注释都格式一致，例如下面的函数注释模板。如果每次写注释都要复制一遍比较麻烦，复制完还要删除多余的字符。但是现有的编辑器一般都支持快捷输入。下面介绍在 VSCode 中如何快捷输入注释模板。

方法

• Ctrl+Shift+P打开编辑器命令窗口 - 输入snippets-选择Preferences:Configure User Snippets-选择·c.json·

  
  

• 更改如下：

  {
  

// Place your snippets for c here. Each snippet is defined under a snippet name and has a prefix, body and // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are: // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the // same ids are connected. // Example: // “Print to console”: { // “prefix”: “log”, // “body”: [ // “console.log(’$1’);”, // “$2” // ], // “description”: “Log output to console” // } “Function comment”: { “prefix”: “funcom”, “body”: [ “/” “ Description: " “Input Parameter: " “ Output Parameter: " “Return: " “/ " ], “description”: “function comment” } ```

• prefix:输入时的缩写，触发器
• body:内容
• description:描述

参考资料

VSCode 利用 Snippets 设置超实用的代码块 - 掘金

配置

首先我们需要下载和编译 QEMU 源码

./configure --enable-debug --target-list=riscv32-softmmu,riscv32-linux-user --enable-kvm

一定要加上--enable-debug，编译出的程序才带有调试信息，不用设置安装路径，编译时会自动在 qemu 文件夹下自动创建一个build文件夹，编译后的程序也在build文件夹下。

用 VSCode 打开qemu-6.X.X文件夹，Ctrl+Shift+D打开调试配置。如果参考过VSCode 中调试程序这篇文章，接下来就很容易。我们只需要将launch.jason文件中的program属性改为${workspaceFolder}/build/qemu-system-riscv32即可。

调试

打开qemu-6.X.X/softmmu/main.c文件，在main函数入口处打上断点，即可开始调试。

现在只需要点击屏幕上的图标，就可以快速的进行单步调试。

如果需要进行命令行操作，在屏幕下方打开DEBUG CONSOLE，输入-exec+正常命令行下的命令即可在命令行中进行更多的调试。如查看断点信息-exec info breakpoints

官方文档

其实最完备安装教程在官方文档里。本文也算是对官方文档的一个翻译版吧。

基于 Debian 和 Ubuntu 的发行版

如果下载了.deb 安装包，那么只需要一个命令就可以完成安装了。

sudo apt install ./<file>.deb

无奈的是，我需要在开发机安装，无法下载安装包，但是我又不想用ftp传来传去，要是apt能完成，绝不单独下载安装包。

可以使用以下脚本手动安装存储库和密钥

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg

sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/

sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'

rm -f packages.microsoft.gpg

更新与安装

sudo apt install apt-transport-https
sudo apt update
sudo apt install code # or code-insiders