自Hugo 0.32开始，界面和其他资源都会打包到Page Bundles

页面资源 和 图像处理 和本节内容是相关的，阅读这些内容可以得到完整的理解

更多参见 Page Bundles

内容的组织

在Hugo中，您的内容应以反映所呈现网站的方式进行组织。

虽然Hugo支持嵌套在任何级别的内容，但顶级（即 content/<DIRECTORIES>）在Hugo中是特殊的，并且被认为是用于确定布局等的内容类型。要阅读有关部分的更多信息，包括如何嵌套它们，请参阅 section。

没有任何其他配置，以下也能工作：

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about/
    ├── posts
    |   ├── firstpost.md   // <- https://example.com/posts/firstpost/
    |   ├── happy
    |   |   └── ness.md  // <- https://example.com/posts/happy/ness/
    |   └── secondpost.md  // <- https://example.com/posts/secondpost/
    └── quote
        ├── first.md       // <- https://example.com/quote/first/
        └── second.md      // <- https://example.com/quote/second/

Hugo中路径分析

下面演示了Hugo网站呈现时内容组织与输出URL结构之间的关系。这些示例假设您使用的是 pretty URLs(https://gohugo.io/content-management/urls/#pretty-urls) ，这是Hugo的默认行为。这些示例还假设您 站点的配置文件 中存在 baseurl ="https://example.com" 键值。

索引页面：_index.md

_index.md在hugo中扮演着特殊的角色。它允许您将 front matter 和内容添加到 list 模板中。list 模板 又包括 section templates, taxonomy templates, taxonomy terms templates, homepage template.

提示：您可以使用.Site.GetPage函数获取_index.md中的内容和元数据的引用。

您可以为主页保留一个 _index.md，在每个content section，taxonomies 和 taxonomies 中保留一个_index.md。下面显示了一个_index.md的典型位置，该位置包含Hugo网站上 post section 页面的内容和 ront matter 内容：

.         url
.       ⊢--^-⊣
.        path    slug
.       ⊢--^-⊣⊢---^---⊣
.           filepath
.       ⊢------^------⊣
content/posts/_index.md

在构建时，这将使用关联的值输出到以下目标：

                     url ("/posts/")
                    ⊢-^-⊣
       baseurl      section ("posts")
⊢--------^---------⊣⊢-^-⊣
        permalink
⊢----------^-------------⊣
https://example.com/posts/index.html

这些部分可以根据需要嵌套。要理解的重要部分是，为了使节树完全导航，至少最下面的部分需要一个内容文件。（即_index.md）。

Sections 中的单个页面

每个Section中的单个内容文件将使用single模板渲染。以下是帖子中单个帖子的示例：

                   path ("posts/my-first-hugo-post.md")
.       ⊢-----------^------------⊣
.      section        slug
.       ⊢-^-⊣⊢--------^----------⊣
content/posts/my-first-hugo-post.md

在构建时，这将使用关联的值输出到以下目标：

                               url ("/posts/my-first-hugo-post/")
                   ⊢------------^----------⊣
       baseurl     section     slug
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
                 permalink
⊢--------------------^---------------------⊣
https://example.com/posts/my-first-hugo-post/index.html

路径解释

以下概念将在构建输出网站时更深入地了解项目组织与Hugo的默认行为之间的关系。

section

默认内容类型由一段内容 section 确定。section由其在 content 目录中的位置决定。section 不能在 front matter 中进行覆盖

slug ¹

内容的slug的默认值 是 name.extension 或 name/ 之一，slug的值由以下规则决定

• 内容文件的名称（例如，lollapalooza.md）或
• 在 front matter 中重写

path

内容的路径由该section的文件路径决定。其中文件路径指：

• 基于在 content 目录中的相对路径 并
• 排除掉slug

url

url是内容的相对URL。url：

• 基于内容在目录结构中的位置 或
• 在 front matter 中重写

通过Front Matter覆盖目标路径

hugo认为，您有目的地组织您的内容。用于组织源内容的相同结构用于组织呈现的站点。如上所示，源内容的组织将在目标中进行镜像。

有时您可能需要对内容进行更多控制。在这些情况下，可以在前面的内容中指定字段以确定特定内容的目的地。

出于特定原因，此顺序中定义了以下项目：列表中进一步说明的项目将覆盖之前的项目，并且并非所有这些项目都可以在前面的事项中定义：

filename

这不在front matter中，而是文件的实际名称减去扩展名。这将是目标中文件的名称（例如，content/posts/my-post.md变为example.com/posts/my-post/）

slug

当在front matter定义时，slug可以取代输出的文件名。

---
title: New Post
slug: "new-post"
---

这将根据Hugo的默认行为将渲染到如下路径：

example.com/posts/new-post/

section

section由内容在磁盘上的位置决定，不能在front matter中指定。有关更多信息，请参阅 部分

type

内容的类型也取决于它在磁盘上的位置，但与section不同，它可以在front matter中指定。参阅 type。当您希望使用不同的布局呈现内容时，这可以特别方便。在下面的示例中，您可以在 layouts/new/mylayout.html 中创建一个布局，Hugo将使用该布局来呈现此内容，即使在许多其他帖子中也是如此。

---
title: My Post
type: new
layout: mylayout
---

url

可以提供完整的URL。这将覆盖所有上述内容，因为它与最终输出关联。这必须是baseURL的路径（以/开头）。url将完全按照前面提供的内容使用，并忽略站点配置中的--uglyURLs设置：

---
title: Old URL
url: /blog/new-url/
---

假设您的baseURL配置为 https://example.com ，则在前面添加url将使old-url.md 渲染到如下路径：

https://example.com/blog/new-url/

您可以在 URL管理 中查看有关如何控制输出路径的更多信息。

假设

• 您已在开发计算机上安装Hugo
• 您已在计算机上安装了git，并且熟悉基本的git用法

安装所有主题

您可以通过在工作目录中克隆GitHub上的整个Hugo Theme存储库来安装所有可用的Hugo主题。根据您的互联网连接，所有主题的下载可能需要一段时间。

git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes

在你使用主题之前，请删除主题目录根目录下的.git目录。如果不，使用git部署将报错

安装单个主题

cd 到themes目录下载指定主题

cd themes
git clone URL_TO_THEME

以下示例显示如何使用“Hyde”主题，其主题源位于https://github.com/spf13/hyde：

cd themes
git clone https://github.com/spf13/hyde

或者，您可以将主题下载为.zip文件，解压缩主题内容，然后将解压缩的源移动到主题目录中。

始终查看主题附带的README.md文件。通常，这些文件包含主题设置所需的进一步说明；例如，从示例配置文件复制值。

主题放置

请确保您已在 /themes 目录中安装了要使用的主题。这是Hugo使用的默认目录。Hugo具有通过您的站点配置中的 themesDir 变量更改主题目录的功能，但不建议这样做。

使用主题

Hugo首先应用已确定的主题，然后应用本地目录中的任何内容。这样可以更轻松地进行自定义，同时保持与主题上游版本的兼容性。要了解更多信息，请转到 自定义主题。

命令行

在Hugo网站上使用主题有两种不同的方法：通过Hugo CLI或作为站点配置文件的一部分。

要通过Hugo CLI更改主题，您可以在构建站点时传递-t标志：

hugo -t themename

可能，您需要在运行Hugo本地服务器时添加主题，特别是如果您要自定义主题：

hugo server -t themename

config 文件

如果您已经确定了网站的主题并且不想使用命令行，则可以将主题直接添加到站点配置文件中：

theme: themename

上面示例中的themename必须与/themes中的特定主题目录的名称相匹配；即目录名称，而不是主题展示站点中显示的主题名称。

这个快速入门在示例中使用了macOS。有关如何在其他操作系统上安装Hugo的说明，请参阅 安装

第1步：安装Hugo

Homebrew是macOS的包管理器，可以通过 brew.sh 安装。如果您正在运行Windows等，请参阅 安装

brew install hugo

验证

hugo version

第2步：创建一个新网站

hugo new site quickstart

以上将在名为quickstart的文件夹中创建一个新的Hugo网站项目

第3步：添加一个主题

请参阅 themes.gohugo.io 以获取要考虑的主题列表。本快速入门使用了美丽的Ananke主题。

cd quickstart

# 下载主题
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
# 非git用户请注意：
#   - 如果您没有安装git，可以从 https://github.com/budparr/gohugo-theme-ananke/archive/master.zip 下载这个主题的最新版本的压缩包
#   - 解压缩这个 .zip 文件到 "gohugo-theme-ananke-master" 目录
#   - 重命名这个目录为 "ananke" ，并移动到 "themes" 目录

# 编辑config.toml配置文件
# 并添加Ananke主题
echo 'theme = "ananke"' >> config.toml

第4步：添加一些Content

hugo new posts/my-first-post.md

如果需要，编辑新创建的内容文件

第5步：启动Hugo服务器

使用启用草稿选项启动Hugo服务

▶ hugo server -D

                   | EN
+------------------+----+
  Pages            | 10
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  3
  Processed images |  0
  Aliases          |  1
  Sitemaps         |  1
  Cleaned          |  0

Total in 11 ms
Watching for changes in /Users/bep/quickstart/{content,data,layouts,static,themes}
Watching for config changes in /Users/bep/quickstart/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

访问你的新网站： http://localhost:1313/

第6步：自定义主题

您的新网站看起来很棒，但在向公众发布之前，您需要稍微调整一下

网站配置

在一个文本编辑器中打开 config.toml

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "ananke"

用更个性化的东西替换上面的标题。此外，如果您已准备好域名，请设置baseURL。请注意，运行本地开发服务器时不需要此值。

提示：在Hugo服务器运行时对站点配置或站点中的任何其他文件进行更改，您将立即看到浏览器中的更改，但您可能需要清除缓存。

有关主题特定的配置选项，请参阅 主题网站

有关进一步的主题自定义，请参阅 自定义主题。

一个 Page Bundles 有两种类型：

• Leaf Bundle (叶子意味着没有孩子)
• Branch Bundle (主页、section、类别项、类别列表)

Leaf Bundles

Leaf Bundle是 content/ 目录中任何层次结构的目录，只要包含index.md文件。

Leaf Bundle 的组织方式的例子

content/
├── about
│   ├── index.md
├── posts
│   ├── my-post
│   │   ├── content1.md
│   │   ├── content2.md
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.md
│   └── my-other-post
│       └── index.md
│
└── another-section
    ├── ..
    └── not-a-leaf-bundle
        ├── ..
        └── another-leaf-bundle
            └── index.md

在上面的示例 content/ 目录中，有四个leaf bundle：

about

位于root级别（直接位于内容目录下），并且只有index.md。

my-post

具有index.md，另外两个内容Markdown文件和两个图像文件。

my-other-post

只有index.md。

another-leaf-bundle

嵌套在几个目录下。该捆绑包也只有index.md。

创建leaf bundle的层次结构深度无关紧要，只要它不在另一个leaf bundle内

无头bundle

无头bundle 是一个配置为不在任何地方发布的 bundle：

• 它没有固定链接（Permalink），也不会渲染到 public 中
• 它不会是.Site.RegularPages等的一部分。

但你可以通过.Site.GetPage获得它。这是一个例子：

{{ $headless := .Site.GetPage "/some-headless-bundle" }}
{{ $reusablePages := $headless.Resources.Match "author*" }}
<h2>Authors</h2>
{{ range $reusablePages }}
    <h3>{{ .Title }}</h3>
    {{ .Content }}
{{ end }}

在这个例子中，我们假设 some-headless-bundle 是一个 无头bundle，包含一个或多个.Name 与 "author *"页面资源。

上面例子的解释：

• 获取 some-headless-bundle Page "object"
• 使用 .Resources.Match 在此页面包中收集与 "author *" 匹配的资源片段
• 遍历该片段的嵌套页面，并输出它们的.Title和.Content

通过在Front Matter中添加以下内容（在index.md中），可以使叶子束无头：

headless = true

只有可以 Leaf Bundles 可以设置为无头

这种无头页面包很有用，比如：

• 共享媒体画廊
• 可重复使用的页面内”片段”

Branch Bundles

分支包是 content/ 目录中任何层次结构的任何目录，至少包含一个 _index.md 文件。

这个 _index.md 也可以直接在 content/ 目录下。

这里以md（markdown）为例。您可以将任何文件类型用作内容资源，只要它是Hugo可识别的内容类型即可。

Branch Bundle组织的示例

content/
├── branch-bundle-1
│   ├── branch-content1.md
│   ├── branch-content2.md
│   ├── image1.jpg
│   ├── image2.png
│   └── _index.md
└── branch-bundle-2
    ├── _index.md
    └── a-leaf-bundle
        └── index.md

在上面的示例 content/ 目录中，有两个 Branch Bundle（和一个 Leaf Bundle）：

branch-bundle-1

此 Branch Bundle 具有_index.md，另外两个内容Markdown文件和两个图像文件。

branch-bundle-2

此 Branch Bundle 具有_index.md，内部嵌套了一个leaf bundle

创建Branch Bundle的层次结构深度无关紧要。

theme = ["my-shortcodes", "base-theme", "hyde"]

你甚至可以嵌套它，让主题组件config.toml中的theme指向自己（主题继承）¹

config.toml中的主题定义示例创建了一个主题，其中包含3个主题组件，从左到右依次为优先级。

对于任何给定的文件，数据输入等，Hugo将首先查看项目，然后是my-shortcode，base-theme，最后是hyde。

Hugo使用两种不同的算法来合并文件系统，具体取决于文件类型：

• 对于i18n和data文件，Hugo使用文件中的翻译ID和数据键深入合并
• 对于静态，布局（模板）和原型文件，这些文件在文件级别合并。因此，将选择最左侧的文件。

这里定义的主题列表必须与/your-site/themes中的目录名严格匹配

还要注意，作为主题一部分的组件可以具有其自己的配置文件，例如，config.toml。目前，主题组件可以配置一些限制：

• params（全局和每种语言）
• menu（全局和每种语言）
• outputformats and mediatypes

这里适用相同的规则：具有相同ID的最左边的参数/菜单等将获胜。上面有一些隐藏的和实验性的命名空间支持，我们将来会努力改进它们，但是鼓励主题作者创建自己的命名空间以避免命名冲突。

有很多关于“hugo由Go语言编写”的讨论，但你不需要安装Go就能使用Hugo。只需安装预编译的二进制文件！

Hugo是用 Go 编写的，支持多个平台。最新版本可以在 Hugo Releases 上找到。

Hugo目前为以下内容提供预构建的二进制文件：

• macOS (Darwin) 的 x64, i386, ARM 架构
• Windows
• Linux
• OpenBSD
• FreeBSD

Hugo可以在任何可以运行Go工具链的平台编译Hugo；例如DragonFly BSD，OpenBSD，Plan 9，Solaris等。有关目标操作系统和编译体系结构的全套支持组合，请参阅 https://golang.org/doc/install/source 。

快速安装

二进制（跨平台）

从 Hugo Releases 下载适用于您的平台的版本。下载后，二进制文件可以从任何地方运行。您无需将其安装到全局位置。这适用于您没有特权帐户的共享主机和其他系统。

Homebrew (macOS)

如果您使用的是macOS并使用 Homebrew，则可以使用以下一行命令安装Hugo：

brew install hugo

有关更详细的说明，请阅读以下安装指南，以便在macOS和Windows上进行安装。

Chocolatey (Windows)

如果您使用的是Windows机器并使用Chocolatey进行包管理，则可以使用以下一行命令安装Hugo：

choco install hugo -confirm

Scoop (Windows)

如果您使用的是Windows计算机并使用Scoop进行包管理，则可以使用以下一行命令安装Hugo：

scoop install hugo

源码

必备工具

• Git
• Go (1.11或更新版本)

从GitHub获取

从Hugo 0.48起，Hugo使用Go 1.11内置的Go Modules支持来构建。最简单的入门方法是将Hugo克隆到GOPATH之外的目录中，如下例所示：

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended

如果您不需要/需要Sass/SCSS支持，请删除–tags扩展。

如果您是Windows用户，请使用％USERPROFILE％替换上面的$HOME环境变量。

其他内容

参见

如果您正在创建一个主题，并计划在Hugo主题网站上分享，请注意以下事项：

• 如果使用内联样式，则需要使用绝对URL，以便正确提供链接资产，例如：<div style ="background：url（'{{"images/background.jpg"| absURL}}'）">
• 确保不要在URL的开头使用正斜杠/因为它将指向主机根。您的主题演示将在Hugo网站的子目录中提供，在这种情况下，Hugo将不会为主题资产生成正确的URL
• 如果使用CDN中的外部CSS和JS，请确保通过https加载这些资产。请不要在主题模板中使用相对协议URL。

Hugo可以使用hugo new命令在现有主题中初始化一个新的空白主题目录：

hugo new theme [name]

主题文件夹

主题组件可以提供以下一个或多个标准Hugo文件夹中的文件：

layouts

用于在Hugo中呈现内容的模板。另请 参阅模板查找顺序。

static

静态文件例如：logos、CSS、JavaScript

i18n

语言包

data

数据文件

archetypes

hugo new 中使用的内容模板

主题配置文件

主题组件还可以提供其自己的配置文件，例如，config.toml。可以在主题组件中配置的内容有一些限制，并且无法覆盖项目中的设置。

可以设置的内容如下

• params（全局和每种语言）
• menu（全局和每种语言）
• outputformats and mediatypes

主题描述文件

除了配置文件之外，主题还可以提供描述主题，作者和原点等的theme.toml文件。请参阅 将您的Hugo主题添加到Showcase

.Hugo.Generator 标签包含在Hugo Themes Showcase 中的所有主题中。我们要求您在Hugo创建的所有网站和主题中包含生成器标签，以帮助核心团队跟踪Hugo的使用情况和受欢迎程度。

测试安装

安装Hugo 后，请确保它位于PATH中。您可以通过help命令测试Hugo是否已正确安装：

hugo help

您在控制台中看到的输出应类似于以下内容：

hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io/.

Usage:
  hugo [flags]
  hugo [command]

Available Commands:
  check       Contains some verification checks
  config      Print the site configuration
  convert     Convert your content to different formats
  env         Print Hugo version and environment info
  gen         A collection of several useful generators.
  help        Help about any command
  import      Import your site from others.
  list        Listing out various types of content
  new         Create new content for your site
  server      A high performance webserver
  version     Print the version number of Hugo

Flags:
  -b, --baseURL string         hostname (and path) to the root, e.g. http://spf13.com/
  -D, --buildDrafts            include content marked as draft
  -E, --buildExpired           include expired content
  -F, --buildFuture            include content with publishdate in the future
      --cacheDir string        filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
      --cleanDestinationDir    remove files from destination not found in static directories
      --config string          config file (default is path/config.yaml|json|toml)
      --configDir string       config dir (default "config")
  -c, --contentDir string      filesystem path to content directory
      --debug                  debug output
  -d, --destination string     filesystem path to write files to
      --disableKinds strings   disable different kind of pages (home, RSS etc.)
      --enableGitInfo          add Git revision, date and author info to the pages
  -e, --environment string     build environment
      --forceSyncStatic        copy all files when static is changed.
      --gc                     enable to run some cleanup tasks (remove unused cache files) after the build
  -h, --help                   help for hugo
      --i18n-warnings          print missing translations
      --ignoreCache            ignores the cache directory
  -l, --layoutDir string       filesystem path to layout directory
      --log                    enable Logging
      --logFile string         log File path (if set, logging enabled automatically)
      --minify                 minify any supported output format (HTML, XML etc.)
      --noChmod                don't sync permission mode of files
      --noTimes                don't sync modification time of files
      --path-warnings          print warnings on duplicate target paths etc.
      --quiet                  build in quiet mode
      --renderToMemory         render to memory (only useful for benchmark testing)
  -s, --source string          filesystem path to read files relative from
      --templateMetrics        display metrics about template executions
      --templateMetricsHints   calculate some improvement hints when combined with --templateMetrics
  -t, --theme strings          themes to use (located in /themes/THEMENAME/)
      --themesDir string       filesystem path to themes directory
      --trace file             write trace to file (not useful in general)
  -v, --verbose                verbose output
      --verboseLog             verbose logging
  -w, --watch                  watch filesystem for changes and recreate as needed

Use "hugo [command] --help" for more information about a command.

Hugo命令

最常见的用法就是直接运行 hugo，当前目录是输入目录。默认情况下，这会将您的网站生成到 public/ 目录，当然可以通过更改 publishDir 字段的输出目录（站点配置）。

命令hugo将网站渲染到 public/ 目录，并准备好部署到您的Web服务器：

hugo
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 90 ms

Draft，Future和Expired内容

Hugo允许你在每篇内容的 front matter 设置 draft （是否是草稿）、 publishdate （发布时间）、 expirydate （过期时间）。默认情况下Hugo不会发布：

• publishdate 值在未来的内容
• draft: true 的内容
• expirydate值在过去的内容

通过在 hugo 和 hugo server 中分别添加以下标志，或者在 配置 中更改分配给同名字段（不带 – ）的布尔值，可以在本地开发和部署期间覆盖所有这三个：

• --buildFuture
• --buildDrafts
• --buildExpired

自动重新载入（LiveReload）

Hugo内置了LiveReload。且不需要额外安装软件包。在开发网站时使用Hugo的一种常用方法是让Hugo使用 hugo server 命令运行服务器并监视更改：

hugo server
0 draft content
0 future content
99 pages created
0 paginator pages created
16 tags created
0 groups created
in 120 ms
Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static}
Serving pages from /Users/yourname/sites/yourhugosite/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop

这将运行功能完备的Web服务器，同时在项目录的以下区域内监视文件系统的添加、删除或更改：

• /static/*
• /content/*
• /data/*
• /i18n/*
• /layouts/*
• /themes/<CURRENT-THEME>/*
• config

每当您进行更改时，Hugo将同时重建网站并继续提供内容。一旦构建完成，LiveReload就会告诉浏览器静默重新加载页面。

大多数Hugo构建都非常快，除非直接在浏览器中查看站点，否则您可能不会注意到更改。这意味着在第二台显示器（或当前显示器的另一半）上保持站点打开，可以让您查看最新版本的网站，而无需离开文本编辑器。

Hugo在模板中 </body> 之前注入了LiveReload <script>，因此如果此标记不存在，则LiveReload将不起作用。

禁用LiveReload

LiveReload通过将JavaScript注入Hugo生成的页面来工作。该脚本创建从浏览器的Web套接字客户端到Hugo Web套接字服务器的连接。

LiveReload非常适合开发。但是，一些雨果用户可能会在生产中使用hugo服务器来即时显示更新的内容。以下方法可以轻松禁用LiveReload：

hugo server --watch=false

或者

hugo server --disableLiveReload

通过将以下键值分别添加到 config.toml 或 config.yml 文件中：

disableLiveReload = true

disableLiveReload: true

部署您的网站

在运行 hugo server 进行本地Web开发之后，最终的需要使用 hugo 命令（不要 server 部分）来重建您的站点。然后，您可以通过将 public/ 目录复制到生产Web服务器来部署站点。

由于Hugo生成静态网站，您的网站可以使用任何Web服务器托管在任何地方。有关由Hugo社区提供的托管和自动化部署的方法，请参阅 主机和部署 。

运行hugo删除上次构建的文件。这意味着您应该在运行hugo命令之前删除您的 /public（或通过标志或配置文件指定的发布目录）。如果您不删除这些文件，则存在不应该出现的文件（例如，drafts或future的帖子），却留在生成的网站中的风险。

开发和部署输出目录

Hugo在构建之前不会删除生成的文件。一个简单的解决方法是针对开发和部署使用不同的输出目录。

要启动构建草稿内容的服务器（有助于编辑），您可以指定不同的目标;例如，dev/ 目录：

hugo server -wDs ~/Code/hugo/docs -d dev

当内容准备好发布时，使用默认的 public/ 目录：

hugo -s ~/Code/hugo/docs

这可以防止草稿内容意外变为可用。

运行 hugo new site 命令 将创建一个包含以下元素的目录结构：

.
├── archetypes
├── assets
├── config
├── content
├── data
├── layouts
├── static
└── themes

目录结构解释

以下是每个目录的高级概述，其中包含指向Hugo文档中各个部分的链接

archetypes

您可以使用hugo new命令在Hugo中创建新的内容文件。默认情况下，Hugo将创建至少包含 data (日期)，title （标题（从文件名推断））和 draft=true 的新内容文件。You can create your own archetypes with custom preconfigured front matter fields as well.你可以自定义front matter来创建自己的archetypes。

assets

存储Hugo Pipes需要处理的所有文件。只有使用.Permalink或.RelPermalink的文件才会发布到公共目录。

config

Hugo附带了大量配置项。config目录是存储格式为JSON，YAML或TOML配置文件的位置。Every root setting object can stand as its own file and structured by environments。如果只需要使用一套配置，可以直接使用项目根目录的单个 config.toml 配置文件

许多站点可能几乎不需要任何配置，但Hugo附带了大量 配置指令，可以更详细地说明您希望Hugo如何构建您的网站。

content

您网站的所有内容都将位于此目录中。content中的所有顶级目录都被叫做 content section 例如，如果您的网站有三个 content section 分别是 content/blog, content/articles, 和 content/tutorials。 Hugo使用sections来分配 默认内容类型

static

存储所有静态内容：图像，CSS，JavaScript等。当Hugo构建您的站点时，静态目录中的所有资源都将按原样复制。使用静态文件夹的一个很好的示例是在Google Search Console上验证网站所有权，您希望Hugo在其中复制整个HTML文件而不修改其内容。

从Hugo 0.31开始，您可以拥有多个静态目录。

从开始学习 Coding 开始，我深入使用过如下几种通用的编辑器/IDE （至于其他专有的IDE比如 Dev C++，不做讨论）

• Eclipse
• Visual Studio
• IntelliJ 系列 (IDEA 等 包括 Android Studio)
• Sublime
• VSCode

根据个人体验上来说，最完美的就是 VSCode。

目前在工作/生活中，所有的与文本文件编辑相关的内容，均采用 VSCode 进行，包括但不限于如下场景：

• 工作计划/每日TODO
• 博客撰写
• Java 项目开发
• React 前端项目开发
• Python 开发
• Scala 开发
• Spark SQL 开发
• Rust 开发（学习阶段）

优势

接下来按照如下几个维度来对 VSCode 的优势进行分析

• 市场指标
• 开源
• 性能
• 外观
• 核心功能

市场指标

截止: 2020年4月

在 https://pypl.github.io/IDE.html 榜单中，VSCode 排名在第 4。较去年2019年4月份上涨 2.2 %。

从趋势上看 自 2015 年发布起，VSCode 持续增长，且增长势头良好。

在VSCode 的 github 仓库，star 数量达到 94.3k。

Sublime 属于个人开发的收费软件。

在 Stack Overflow Developer Survey Results 2019 中 VSCode 在 Most Popular Development Environments 榜单中排名第一

开源

完全开源，开源协议为 MIT，与之类似的就只有 Eclipse了。

IntelliJ 属于部分开源，其专业版属于收费软件。

VSCode 的主要贡献团队 是微软，近几年微软在开源项目上的投入有目共睹。

团队负责人：Erich Gamma JUnit 作者之一，《设计模式》作者之一， Eclipse 架构师。2011 加入微软，在瑞士苏黎世组建团队开发基于 web 技术的编辑器，也就是后来的 monaco-editor。VSCode 开发团队从 10 来个人开始，早期成员大多有 Eclipse 开发团队的背景。

性能

启动速度

VSCode 从设计上之处就追求极致的性能，本质上是一个轻量级 编辑器，因此可以在性能较弱的设备中实现秒级打开。不同于 Atom，其扩展机制保证了在安装大量扩展的情况下，VSCode仍然有较快的启动速度。在启动速度上可能只有 Sublime 可以与之相提并论。

相较于 Eclipse 、 Visual Studio 和 IntelliJ 之类的重量级 IDE来说，其启动速度是绝对的领先。

空间占用

目前（2020-04-11），Mac端的Zip文件大小仅 82.9MB，app文件大小，200MB左右。在空间方面，只有 Sublime 可以与之相提并论。

相较于 Eclipse 、 Visual Studio 和 IntelliJ 之类的重量级 IDE来说可谓非常小

响应速度

由于轻量级的特性（基于 Electron），响应速度上非常快。而基于 Java 开发的 UI（Eclipse、IntelliJ 系列），响应缓慢，有时会遇到卡顿。

外观

VSCode 在 UI 上相对来说比较现代化，各种第三方主题几乎可以满足所有 程序员对 UI 上的执念。

扩展虽然无法修改 VSCode 的 UI 结构（仅可以更改主题，未来，正在预览阶段的 Custom text editors 可以做更深层次的定制），看似定制程度低，但从另一方面看，这显著降低了用户在UI认知上的心智成本，也就是说，一旦梳理了VSCode交互的套路，所有扩展程序的表现都是可以预测的。

核心功能

VSCode 的核心竞争力是设计优良架构和扩展机制

• 极强的扩展能力，几乎编辑器的所有方面都可以进行扩展
• 丰富的扩展商店，你想要的几乎都有，即使没有自己动手实现一个呗
• 扩展与编辑器内核的松耦合（通过RPC进行通信），因此可以实现独一份的 Remote Develop
• 扩展几乎不会拖慢启动速度
• UI 基于 Electron
  • 原则上支持所有平台
  • 因为 Electron 本质上是基于 Chromium，因此可以实现 在浏览器上进行开发的 Visual Studio Online

在扩展开发技术栈方面，原生支持 通过 JavaScript（TypeScript）开发，因此可以享受 前端生态的红利。对于其他开发语言，可以通过语言服务器的方式进行扩展开发。

总结

• 性能优秀
• 外观现代化，定制化程度高
• 丰富强大扩展机制
• 独有的全功能的远程开发与浏览器开发能力

站点

• 官方网站
• 官方文档
• 扩展商店
• 极客教程-VSCode （推荐）

Hugo使用 config.toml，config.yaml或config.json（如果在站点根目录中找到）作为默认站点配置文件。

用户可以使用命令行 --config 开关选择使用一个或多个站点配置文件覆盖该默认值。

例子

hugo --config debugconfig.toml
hugo --config a.toml,b.toml,c.toml

可以将多个站点配置文件指定为–config开关的逗号分隔字符串。

配置目录

除了使用单个站点配置文件之外，还可以使用 configDir目录（默认为 config/ ）来维护更轻松的组织和环境特定设置。

• 每个文件代表一个配置根对象，例如Params，Menus，Languages等……
• 每个目录包含一组包含环境特有的设置的文件。

• 文件可以本地化为特定于语言。

  config
  ├── _default
  │   ├── config.toml
  │   ├── languages.toml
  │   ├── menus.en.toml
  │   ├── menus.zh.toml
  │   └── params.toml
  ├── staging
  │   ├── config.toml
  │   └── params.toml
  └── production
  ├── config.toml
  └── params.toml

考虑到上面的结构，当运行 hugo --environment staging 时，Hugo将使用config/_default 中的每个设置并在这些设置之上合并 staging。

hugo server 的默认环境是 development，hugo 的默认环境是 production

所有配置设置

以下是Hugo定义的变量的完整列表，其默认值在括号中。用户可以选择在其站点配置文件中覆盖这些值。

archetypeDir ("archetypes")

内容模板目录配置

assetDir ("assets")

参见 Hugo Pipes.

baseURL

网站根URL, e.g. http://bep.is/

blackfriday

Markdown解析器配置参见 Configure Blackfriday

buildDrafts(false)

构建时包含草稿(draft: true)

buildExpired (false)

构建时包含已过期(expirydate 在过去)的内容

buildFuture (false)

构建时包含 publishdate 时间在未来的内容

caches

参见 Configure File Caches

canonifyURLs (false)

启用将相对URL转换为绝对URL

contentDir ("content")

内容目录设置

dataDir ("data")

数据目录设置

defaultContentLanguage ("en")

内容的默认语言

defaultContentLanguageInSubdir (false)

在子目录中渲染默认语言的内容，例如 / 重定向到 /en/

disableAliases (false)

将禁用别名重定向的生成。请注意，即使设置了disableAliases，也会在页面上保留别名本身。这样做的动机是能够使用自定义输出格式在.htacess，Netlify _redirects文件或类似文件中生成301重定向。

disableHugoGeneratorInject (false)

禁用hugo生成器头

disableKinds ([])

启用禁用指定种类的所有页面，允许列表如下 ["page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"]

disableLiveReload (false)

禁用浏览器窗口的自动实时重新加载。

disablePathToLower (false)

不要将url/path转换为小写。

enableEmoji (false)

启用 Emoji

enableGitInfo (false)

为每个页面启用.GitInfo对象（如果Hugo站点由Git进行版本控制）。然后，这将使用该内容文件的最后一个git提交日期更新每个页面的Lastmod参数。

enableInlineShortcodes

参见 Inline Shortcodes.

enableMissingTranslationPlaceholders (false)

如果缺少翻译，则显示占位符而不是默认值或空字符串

enableRobotsTXT (false)

启用robots.txt文件的生成

frontmatter

参见 Front matter Configuration

footnoteAnchorPrefix ("")

脚注锚点的前缀

footnoteReturnLinkContents ("")

脚注返回链接显示的文本。

googleAnalytics ("")

Google Analytics跟踪ID

hasCJKLanguage (false)

如果为true，则在内容中自动检测中文/日文/韩文语言。这将使.Summary和.WordCount在CJK语言中正常运行。

imaging

参见 Image Processing Config

languages

参见 Configure Languages

languageCode ("")

设置站点语言代码

languageName ("")

设置站点语言名

disableLanguages

参见 https://gohugo.io/content-management/multilingual/#disable-a-language

layoutDir ("layouts")

布局（模板）目录

log (false)

使能日志

logFile ("")

配置日志文件

menu

参见 Add Non-content Entries to a Menu

metaDataFormat ("toml")

Front matter格式. 允许值为: “toml”, “yaml”, or “json”.

newContentEditor ("")

创建新内容时使用的编辑器。

noChmod (false)

不要同步文件的权限模式

noTimes (false)

不要同步文件的修改时间

paginate (10) :配置分页数 pagination

paginatePath ("page")

分页路径 (例如https://example.com/page/2).

permalinks

参见 Content Management

pluralizeListTitles (true)

如果某个目录没有_index.md，此列表页页面标题将会转换为复数形式（针对英语）

publishDir ("public")

Hugo将编写最终静态站点（HTML文件等）的目录。

pygmentsCodeFencesGuessSyntax (false)

在没有指定语言的情况下为代码栅栏启用语法猜测。

pygmentsStyle ("monokai")

用于语法突出显示的颜色主题或样式。请参阅Pygments Color Themes

pygmentsUseClasses (false)

启用外部CSS以进行语法突出显示。

related

请参阅 Related Content

relativeURLs (false)

启用此选项可使所有相对URL相对于内容根目录。请注意，这不会影响绝对URL

refLinksErrorLevel ("ERROR")

使用ref或relref解析页面链接并且无法解析链接时，将使用此logg级别记录该链接。有效值为ERROR（默认值）或WARNING。任何ERROR都将使构建失败（退出-1）。

refLinksNotFoundURL

使用ref或relref解析页面链接并且无法解析链接时，将使用此logg级别记录该链接。有效值为ERROR（默认值）或WARNING。任何ERROR都将使构建失败（退出-1）

rssLimit (unlimited)

RSS源中的最大项目数

sectionPagesMenu ("")

参见 Section Menu for Lazy Bloggers.

sitemap

参见 sitemap configuration

staticDir ("static")

静态文件目录 参见 静态文件

stepAnalysis (false)

显示程序的不同步骤的存储器和时序

summaryLength (70)

摘要长度

taxonomies

分类，参阅 Configure Taxonomies

theme ("")

主题 要使用的主题（默认位于/themes/THEMENAME/）

themesDir ("themes")

主题目录

timeout (10000) :生成页面内容的超时，以毫秒为单位（默认为10秒）。注意：这用于避免递归内容生成，如果您的页面生成缓慢（例如，因为它们需要大型图像处理或依赖于远程内容），您可能需要提高此限制。

title ("")

站点标题

uglyURLs (false)

启用后，创建格式为/filename.html而不是/filename/的URL。

verbose (false)

启用详细输出

verboseLog (false)

启用详细日志输出

watch (false)

监视文件系统以进行更改并根据需要重新创建

如果您在* nix机器上开发站点，这是从命令行查找配置选项的便捷快捷方式：

cd ~/sites/yourhugosite
hugo config | grep emoji

输出类似如下

enableemoji: true

配置环境变量

HUGO_NUMWORKERMULTIPLIER

可以设置为增加或减少Hugo中并行处理中使用的工作者数量。如果未设置，将使用逻辑CPU的数量。

配置查找顺序

与模板查找顺序类似，Hugo有一组默认规则，用于在网站源目录的根目录中搜索配置文件，作为默认行为：

• ./config.toml
• ./config.yaml
• ./config.json

在您的配置文件中，您可以指导Hugo了解您希望网站呈现的方式，控制网站的菜单，以及任意定义特定于项目的网站范围参数。

示例配置

baseURL = "https://yoursite.example.com/"
footnoteReturnLinkContents = "↩"
title = "My Hugo Site"

[params]
  AuthorName = "Jon Doe"
  GitHubUser = "spf13"
  ListOfFoo = ["foo1", "foo2"]
  SidebarRecentLimit = 5
  Subtitle = "Hugo is Absurdly Fast!"

[permalinks]
  posts = "/:year/:month/:title/"

使用环境变量配置

除了已经提到的3个配置选项之外，还可以通过操作系统环境变量定义配置键值。

例如，以下命令将在类Unix系统上有效地设置网站标题：

env HUGO_TITLE="Some Title" hugo

如果您使用Netlify等服务部署您的站点，这非常有用。查看 [Netlify configuration file] 示例。

名称必须以HUGO_为前缀，并且在设置操作系统环境变量时必须将配置键设置为大写。

渲染时忽略文件

./config.toml中的以下语句将导致Hugo在呈现时忽略以.foo和.boo结尾的文件：

ignoreFiles = [ "\\.foo$", "\\.boo$" ]

以上是正则表达式列表。请注意，在此示例中对反斜杠（\）字符进行了转义，以使TOML能够理解。

配置Front Matter

配置日期

日期在Hugo中非常重要，您可以配置Hugo如何为您的内容页面分配日期。您可以通过向config.toml添加frontmatter部分来完成此操作。

默认配置如下

[frontmatter]
date = ["date", "publishDate", "lastmod"]
lastmod = [":git", "lastmod", "date", "publishDate"]
publishDate = ["publishDate", "date"]
expiryDate = ["expiryDate"]

例如，如果您在某些内容中包含非标准日期参数，则可以覆盖日期设置：

[frontmatter]
date = ["myDate", ":default"]

:default是默认设置的快捷方式。如果myDate存在，上面将设置.Date为myDate中的日期值，如果不存在，我们将查看 ["date", "publishDate", "lastmod"] 并选择第一个有效日期。

在列表中，以":"开头的值是具有特殊含义的日期处理程序（见下文）。其他只是前端配置中日期参数的名称（不区分大小写）。另请注意，Hugo上面有一些内置别名：lastmod => modified，publishDate => pubdate，published和expiryDate => unpublishdate。以此为例，默认情况下，将pubDate用作前面的日期，将分配给.PublishDate。

特殊日期处理程序是：

:fileModTime

从内容文件的上次修改时间戳中获取日期。

一个例子：

[frontmatter]
lastmod = ["lastmod", ":fileModTime", ":default"]

上面将首先尝试从front matter参数中的 lastmod 提取.Lastmod的值，然后是内容文件的修改时间戳。最后，在这里不需要默认，但Hugo最终会在：git，date和publishDate中寻找有效的日期。

:filename

从内容文件的文件名中获取日期。例如，2018-02-22-mypage.md将提取日期2018-02-22。此外，如果未设置slug，mypage将用作.Slug的值。

一个例子：

[frontmatter]
date  = [":filename", ":default"]

上面将首先尝试从文件名中提取.Date的值，然后它将查看前面的参数date，publishDate和last last last。

:git

这是此内容文件的最新修订版的Git作者日期。只有在设置了--enableGitInfo或在站点配置中设置了enableGitInfo = true时才会设置此项。

配置Blackfriday

Blackfriday 是Hugo内置的Markdown渲染引擎。

Hugo通常使用理智的默认值配置Blackfriday，这些默认值应该适合大多数用例。

但是，如果您对Markdown有特殊需求，Hugo会公开其部分Blackfriday行为选项供您更改。下表列出了这些Hugo选项，与Blackfriday的源代码（ html.go 和 markdown.go ）中的相应标志配对。

Blackfriday选项

参见

配置其他输出格式

Hugo v0.20引入了将内容呈现为多种输出格式（例如，JSON，AMP html或CSV）的功能。有关如何将这些值添加到Hugo项目的配置文件的信息，请参阅 输出格式。

配置文件缓存

从Hugo 0.52开始，您可以配置的不仅仅是 cacheDir。这是默认配置：

[caches]
[caches.getjson]
dir = ":cacheDir/:project"
maxAge = -1
[caches.getcsv]
dir = ":cacheDir/:project"
maxAge = -1
[caches.images]
dir = ":resourceDir/_gen"
maxAge = -1
[caches.assets]
dir = ":resourceDir/_gen"
maxAge = -1

您可以在自己的config.toml中覆盖任何这些缓存设置。

关键词解释

:cacheDir

这是cacheDir配置选项的值（如果已设置）（也可以通过OS env变量HUGO_CACHEDIR设置）。它将回退到Netlify上的 /opt/build/cache/ hugo_cache/，或其他人的OS temp dir下面的hugo_cache目录。这意味着如果在Netlify上运行构建，则将在下一个构建中保存和恢复所有配置有：cacheDir的缓存。对于其他CI供应商，请阅读他们的文档。对于CircleCI示例，请参阅此配置。

:project

当前Hugo项目的基本目录名称。这意味着，在其默认设置中，每个项目都将具有单独的文件缓存，这意味着当您执行hugo –gc时，您将不会触摸与在同一台PC上运行的其他Hugo项目相关的文件。

:resourceDir

这是resourceDir配置选项的值。

maxAge

这是缓存条目被逐出之前的持续时间，-1表示永远，0有效地关闭该特定缓存。使用Go的time.Duration，因此有效值为“10s”（10秒），“10m”（10分钟）和“10h”（10小时）。

dir

将存储此缓存的文件的绝对路径。允许的起始占位符是：cacheDir和：resourceDir（见上文）。

配置文件语法

• TOML Spec
• YAML Spec
• JSON Spec

rust-lang/rfcs

Rust rfc 现状

rust-lang/rfcs 代码库概览

• README.md，说明 RFC 的目的是什么，何时需要提交 RFC（何时不需要），RFC 如何编写，如何提交 RFC，RFC 生命周期如何管理
• style-guide RFC 中代码样式规范
• text RFC 文档的存储目录

简述

大多数变更，比如 bugfix 、文档，通过 Pull Request 完成

但是某些 “实质性” 的变更，需要通过一些设计过程，让社区达成共识

RFC (request for comments) 流程，旨在为新特性进入语言和标准库提供一致和受控的路径。帮助所有的利益相关方都可以对语言在不断发展的方向上有信心

什么场景触发 RFC 流程

如果您打算对Rust，Cargo，CrateS.IO 或 RFC 过程本身进行“实质性”更改，则需要遵循此过程。基于社区规范的 “实质性” 变更是什么构成的，并根据您提出改变的生态系统的哪个部分而变化，但可能包括以下内容。

• 任何非 bugfix 的 想进入语言的 语义或语法更改
• 删除语言功能，包括 “feature-gated”
• 编译器和库之间的接口，包括LANG项目和内部 的更改
• 添加到 std

不需要RFC的变更：

• 重建，重组，重构或以其他方式 “变化形态但不会改变意义” 的变更
• 添加严格改善客观，数值质量标准（警告移除，加速，更好的跨平台新，并发度，陷阱和错误等）
• 只对开发人员可见对 rust 用户不可见的变更

提交须知

如下提案可能被快速拒绝

• 低质量的提案
• 以前拒绝的 feature 的提案
• 不适合近期路线图的提案

官方论坛

• 在官方 Discord 上讨论了讨论我们开发人员讨论论坛的主题
• 偶尔在开发人员论坛上发布 “pre-RFCs” 。您可以在此仓库中提交问题进行讨论，但这些次数不会被团队积极地查看。

作为经验丰富的规则，接受了从长远的项目开发人员的鼓励反馈，特别是相关子团队的成员是一个很好的迹象表明RFC值得追求。

RFC 流程

• Fork rfc repo
• 将 0000-template.md 复制到 text/0000-my-feature.md（其中 “my-feature” 是描述性的）。不要分配RFC号码；这将是PR号码，如果接受RFC，我们将相应地重命名文件。
• 填写RFC，需要注意细节：没有提出令人信服的动机、对设计的影响缺乏了解、或对缺点或替代方案不诚实的建议性文件往往不受欢迎。
• 提交一个 PR 请求。作为一个 PR，RFC将从更大的社区收到设计反馈，作者应该准备好修改它作为回应。
• 该 RFC 的编号将是 PR 的 ID
• 每个 PR 将添加上最相关的 子团队 的 label
• 建立共识，整合反馈。获得广泛支持的RFC比那些没有收到任何意见的RFC更有可能取得进展。特别是随时可以联系RFC受让人，以获得确定利益相关者和障碍的帮助。
• 子团队将在 RFC 尽量在 PR 下中进行讨论，离线讨论的总结将发表到 PR 中
• RFC很少会一成不变地通过这个过程，特别是当替代方案和缺点被展示出来的时候。你可以对 RFC 进行大大小小的修改，以澄清或改变设计，但要以新 commit 的方式提交到 PR 中，并在 PR 中留下评论，解释你的修改。具体来说，不要在 PR 上可见后再 Squash 或 Rebase 提交。
• 在某些时候，小组的成员将提出 “最后论期动议” （FCP），以及RFC的处理（合并，关闭或推迟）
  • 当讨论了足够多的权衡，小组能够做出决定时，就会采取这一步骤。这并不要求RFC线的所有参与者达成共识（这通常是不可能的）。然而，支持 RFC 处置的论点需要已经被清楚地表达出来，而且在子团队之外不应该有强烈的反对该立场的共识。分组成员在采取这一步骤时，要运用他们的最佳判断力，而FCP本身也要确保有足够的时间和通知，让利益相关者在过早做出决定的情况下进行反击。
  • 对于讨论时间较长的RFC，在提出FCP动议之前，通常会有一个总结性意见，试图说明讨论的现状和主要的权衡/分歧点。
  • 在真正进入FCP之前，所有的子团队成员必须签字；这往往是许多子团队成员第一次全面深入审查RFC的时刻。
• 在大多数情况下，FCP期间是平静的，RFC要么被合并，要么被关闭。然而，有时会有大量新的论点或想法被提出，FCP被取消，RFC又回到发展模式。

RFC 生命周期

• 一旦一个RFC变得 “活跃”，那么作者就可以实现它，并将该功能作为 PR 提交到Rust repo。”活跃” 并不是橡皮图章，尤其是并不意味着该功能最终会被合并；它确实意味着原则上所有主要的利益相关者都同意该功能，并且愿意合并它。
• 此外，一个给定的RFC已经被接受并且是 “活跃的” 这一事实并不意味着它的实现被分配了什么优先级，也不意味着是否有一个Rust开发者被分配了实现该功能的任务。虽然RFC的作者不一定要写实现，但这是迄今为止看到RFC完成的最有效的方式：作者不应该期望其他项目开发者会承担实现他们所接受的功能的责任。
• 对 “活动” RFC的修改可以在后续的 PR 中进行。我们努力以反映该功能最终设计的方式来编写每一个RFC；但这个过程的性质意味着我们不能期望每一个合并的RFC都能实际反映下一个主要版本时的最终结果。
• 一般来说，RFC一旦被接受，就不应该进行实质性的修改。只有非常小的改动才应作为修正案提交。更多的实质性修改应该是新的RFC，并在原RFC上添加注释。确切地说，什么是 “非常小的改动” 是由分团队决定的；更多细节请查看分团队的具体指南。

审查 RFC

• 在 RFC PR 发布的同时，子团队可能会安排与作者 and/or 相关利益相关者的会议，以更详细地讨论问题，在某些情况下，该主题可能会在分小组会议上讨论。不管是哪种情况，会议的摘要都会发布到RFC PR 中。
• 在充分了解利弊之后，子团队做出最终决定。这些决定可以在任何时候做出，但分团队会定期发布决定。当做出决定后，RFC拉动请求将被合并或关闭。无论哪种情况，如果在线的 PR 讨论区中没有讨论清楚，子团队需要加上评论，并说明决定的理由。

实现 RFC

• 一些被接受的RFC代表了需要立即实施的重要功能。其他被接受的RFC可以代表一些可以等到一些任意的开发者觉得喜欢做的功能。每一个被接受的RFC都有一个相关的问题，跟踪它在Rust仓库中的实现情况；因此，相关的问题可以通过团队对Rust仓库中所有问题的分流过程分配一个优先级。
• RFC的作者没有义务去实现它。当然，欢迎RFC作者(像其他开发者一样)在RFC被接受后将其实施情况张贴出来供审查。
• 如果你对一个 “活跃的” RFC 的实现感兴趣，但又不能确定是否已经有人在做，请随时提出问题（例如，在相关 issue 上留下评论）。

延期 RFC

• 一些 RFC 拉取请求在关闭时（作为拒绝过程的一部分）会被贴上 “推迟 “标签。用 “postponed” 标签关闭的RFC，是因为我们既不想评估这个提案，也不想在未来的某个时候实现所描述的特性，而且我们相信我们有能力等到那个时候再去做。历史上，”postponed” 是用来推迟到1.0之后的特性。推迟的拉取请求可能会在时机成熟时重新开放。我们没有任何正式的流程，你应该询问相关子团队的成员。
• 通常，标记为 “推迟” 的RFC拉取请求已经通过了非正式的第一轮评估，即 “我们是否认为我们可能会考虑做出RFC拉取请求中概述的这一改变，或者它的一些半明显的变体”。(当后一个问题的答案是 “不 “时，适当的回应是关闭RFC，而不是推迟它)。

Help this is all too informal

这个过程的目的是为了在目前的情况下尽可能的轻量化。一如既往，我们试图让这个过程由共识和社区规范驱动，而不是强加更多不必要的结构。

Rust rfc 模板

整体结构

• 头部元信息
• 摘要
• 动机
• 指南级别的解释
• 参考级别解释
• 缺点
• 理由和替代方案
• 现有技术
• 未解决的问题
• 未来的可能性

文件名

0000-feature-name.md

头部元信息

Feature Name: (fill me in with a unique ident, my_awesome_feature)
Start Date: (fill me in with today's date, YYYY-MM-DD)
RFC PR: rust-lang/rfcs#0000
Rust Issue: rust-lang/rust#0000

• Feature Name: 特性唯一标识（和文件名没有关系）
• Start Date: 启动时间
• RFC PR: 当前 PR 的链接，PR 的 id 将作为 RFC 的编号

摘要

我们为什么要这样做？它支持哪些用例？预期的结果是什么？

指南级别的解释

解释该提案，好像它已被包含在语言中，并且您正在向另一个 Rust 程序员传授它。这通常意味着：

• 引入新的命名概念
• 主要用例子来解释这个特性
• 解释 Rust 程序员应该如何思考这个特性，以及它应该如何影响他们使用 Rust 的方式。它应该尽可能具体地解释影响。
• 如果适用，提供错误信息、废弃警告或迁移指导的示例。
• 如果适用，描述向现有的 Rust 程序员和新的 Rust 程序员教授这个功能的区别。

对于以实现为导向的RFC（例如，编译器内部），本节应专注于编译贡献者如何考虑变革，并举例说明其具体影响。对于政策RFC，本节应提供对政策的示例驱动的介绍，并在具体方面解释其影响。

参考级别解释

这是RFC的技术部分。以足够的细节解释设计：

• 该功能与其他功能的相互作用是明确的。
• 合理地明确了如何实现该功能。
• 通过示例解剖视角案例。

本节应回到上一节所举的例子，并更充分地解释详细提案如何使这些例子发挥作用。

缺点

存在缺点

理由和替代方案

• 为什么在可能的设计中，这种设计是最好的？
• 还考虑过哪些其他设计，不选择这些设计的理由是什么？
• 不这样做的影响是什么？

现有技术

讨论与本提案有关的现有技术，包括好的和坏的。其中可包括以下几个例子：

• 对于语言、库、crate、工具和编译器的建议。这个功能在其他编程语言中是否存在？ 他们的社区有什么经验？
• 对于社区的建议。是否有其他社区做了这个功能，他们有什么经验？
• 对于其他团队来说。我们可以从其他社区在这里做的事情中学到什么经验？
• 论文。有没有发表过的论文或者是讨论这个问题的好帖子？如果你有一些相关的论文可以参考，这可以作为一个更详细的理论背景。

本节旨在鼓励您作为作者思考其他语言的经验教训，为您的RFC读者提供更全面的信息。如果没有先例，那也没关系–无论你的想法是全新的，还是从其他语言改编而来，我们都会感兴趣。

请注意，虽然其他语言创造的先例是一些动力，但它本身并不能成为RFC的动力。也请考虑到rust有时会故意偏离通用语言的特性。

未解决的问题

• 在这个功能被合并之前，你期望通过RFC程序解决设计中的哪些部分？
• 在稳定化之前，你期望通过这个功能的实现来解决设计中的哪些部分？
• 您认为哪些相关问题不在本 RFC 的范围内，可以在未来独立于本 RFC 的解决方案解决？

未来的可能性

想一想你的提案的自然延伸和演变会是什么，以及它将如何整体地影响语言和项目。试着把这部分作为一个工具，在你的提案中更全面地考虑所有可能与项目和语言的互动。同时考虑这一切如何与项目和相关子团队的路线图相适应。

这也是一个 “倾倒想法 “的好地方，如果这些想法不在你正在编写的RFC范围内，但在其他方面是相关的。

如果你已经尝试过，但想不出任何未来的可能性，你可以简单地声明你想不出任何东西。

请注意，在未来可能性部分写下一些东西并不是接受当前或未来 RFC 的理由；这样的说明应该在本 RFC 或后续 RFC 的动机或理由部分。这一节只是提供补充信息。

Rust 一个 rfc 的例子

1210-impl-specialization.md

Rust rfc 自描述 rfc

0002-rfc-process.md

简介

https://code.visualstudio.com/docs/remote/remote-overview 发行日志 https://github.com/microsoft/vscode-docs/tree/master/remote-release-notes

远程开发是，19年 VSCode 推出的一项重大特性。因此将 《远程开发》 章节作为 VSCode 优质扩展的第一篇。

近几年来 云 十分火爆，因此各种 云 IDE 应运而生。但是这也云 IDE 在功能上与本地IDE无法相提并论。

而 VSCode 的 Remote Development，真正实现了不损失功能的情况下实现了远程开发，而且配置简单，在使用上和本地 VSCode 几乎没有差别，这对于开发者来说是非常大的福音。

Visual Studio Code远程开发允许您将容器，远程主机或Windows子系统（WSL）用作完整功能的开发环境。您可以：

• 在您部署到的同一操作系统上进行开发，或使用更大或更专业的硬件。
• 将开发环境沙盒化，以避免影响本地计算机配置。
• 使新贡献者易于上手，并使每个人都保持一致的环境。
• 使用本地操作系统上不可用的工具或运行时，或管理它们的多个版本。
• 使用Linux的Windows子系统开发部署了Linux的应用程序。
• 从多台机器或位置访问现有的开发环境。
• 调试在其他位置（例如客户站点或云中）运行的应用程序。

场景

远程开发

有时，迫于现状，正在开发的项目依赖特定的环境（比如：操作系统/网络隔离/宿主环境），导致在本地运行和调试程序及其困难甚至不可能。另外，在和线上环境相同的环境下开发，可以杜绝因为环境不同导致的问题。

此时每次开发可能这样的流程：

• 本地开发
• 利用git、ftp、sftp、scp等手段同步到开发机
• 在开发机启动程序，观察日志输出

一般情况下，以上流程虽然较长，但是可以接受，但是在 Debug 的时候需要频繁修改代码 各种 print。开发效率及其低下的。

在使用 VSCode Remote Development 后，只需要做一次前序操作：

• 安装 Remote Development 扩展
• 连接到远端主机，并打开项目
• 在远端安装扩展

此后，就可以像在本地开发一样进行开发。

利用 Remote Development 开发还有如下好处

• 如果远程主机性能很强，则可以提高编译速度和扩展的响应速度
• 自己的本地机器不会因为扩展的语言服务器在进行CPU密集的运算而造成风扇狂响了

远程开发需要付出的代价

• 与远程主机较好的网络连接（带宽不必要求太高，延迟越低越好）

一致性开发环境（敏捷）

在 敏捷开发/持续交付 要求可以快速的搭建开发环境， Docker 容器化是实现该需求的关键。

当容器技术和VSCode结合，不管项目如何复杂，都可以真正实现

• 所有成员开发环境一致
• 开发环境快速搭建
• 开发环境统一管理

原理

https://code.visualstudio.com/docs/remote/remote-overview

整体架构

Remote - SSH 架构

安装

命令安装

• ext install ms-vscode-remote.vscode-remote-extensionpack
  • ext install ms-vscode-remote.remote-ssh
    • ext install ms-vscode-remote.remote-ssh-edit
  • ext install ms-vscode-remote.remote-wsl
  • ext install ms-vscode-remote.remote-containers
• ext install ms-vsonline.vsonline

商店链接

• 扩展包 Remote Development
  • Remote - SSH
    • Remote - SSH: Editing Configuration Files
  • Remote - WSL
  • Remote - Containers
• Visual Studio Online

特性

远程开发

Remote - SSH

相关链接

• Remote Development using SSH

使用说明

常用命令

• >remote ssh: connect to host 连接到远端Server
• >remote ssh: open configuration file 打开 ssh 配置文件
• >remote ssh: settings 打开设置
• >remote-ssh:show log 打开日志

基本使用

• 进入 >remote ssh: connect to host 命令
• 选择 ssh config 已经配置好的主机或者输入用户名主机信息，形如 username@host

技巧

• 通过 ~/.ssh/config 可以方便的管理 server 列表，可通过 >remote ssh: open configuration file 命令打开
• 通过 活动栏 图标打开 远程资源管理器，可以查看所有可以历史打开的远程工作区，方便一键打开远程开发
• 远程开发的窗口，与本地开发窗口不同点在于
  • 扩展视图：添加了安装到远程的特性
  • 设置视图：添加了远程主机的设置，优先级 在 工作区 和 用户设置之间。

提示

• 通过 remote SSH 连接主机，需要进行如下配置
  • 远程主机开启 sshd 服务，且开启ssh端口
  • （不强制，单非常建议）配置 主机 通过 key-based 验证（所谓的免密登录），最简单的方式是在本地设备执行如下命令 （参考）
    • 如果本地设备没有公私钥需要执行 ssh-keygen -t rsa -C "your_email@example.com"
    • 将公钥拷贝到远端 ssh-copy-id username@host

• 连接失败，安装如下步骤进行检查

  • 配置 "remote.SSH.showLoginTerminal": true, 观察是否需要输入密码
  • 在连接远端的VSCode 窗口执行 >remote-ssh:show log 观察输出

  • 进入远端主机可以尝试，杀死进程并清理文件

    kill -9 `ps ax | grep "remoteExtensionHostAgent.js" | grep -v grep | awk '{print $1}'`
    kill -9 `ps ax | grep "watcherService" | grep -v grep | awk '{print $1}'`
    rm -rf ~/.vscode-server # Or ~/.vscode-server-insiders

常用配置

{
    // 连接远端自动安装的扩展列表
    "remote.SSH.defaultExtensions": [
        // 常用工具
        "editorconfig.editorconfig",
        "donjayamanne.githistory",
        "codezombiech.gitignore",
        // Java
        "vscjava.vscode-java-pack",
        "gabrielbb.vscode-lombok",
        "pivotal.vscode-boot-dev-pack",
        // Python
        "ms-python.python",
    ],
    // 配置端口转发
    "remote.SSH.defaultForwardedPorts": [
        {
            "localPort": 8080,
            "name": "example",
            "remotePort": 8080
        }
    ],
    // 使用密码登录的时候需要
    "remote.SSH.showLoginTerminal": true
}

Remote - Containers

Remote - SSH 解决了远程开发的问题，但是本质上还是 个人 的 定制的环境，仍然不够敏捷。

通过 Remote - Containers 可以做到团队项目成员一致性的环境、真正快速的搭建开发环境、开发环境统一管理。可以极大的降低大型项目的环境搭建问题。

其他扩展

参见：官网文档

和普通软件安装方式一致，进入官方网站后，点击 Download for xxx，安装即可，在此不做赘述。

详细文档参见 setup

UI

更多参见 User Interface

本质上，Visual Studio Code是代码编辑器。其基本布局如下：

• A - Activity Bar 最左侧为活动栏，由于切换 Side Bar
• B - Side Bar 侧边栏，包含诸如资源管理器之类的不同视图，可在您处理项目时为您提供帮助。
• C - Editor Group 编辑器组，最大的主要区域。您可以在垂直和水平方向上并排打开任意多个编辑器。
• D - Panel 面板，包含四种页面，问题、输出、调试控制台、终端
• E - Status Bar 最下方为状态栏，展示 打开的项目和编辑的文件的状态信息。

活动栏

• 右击活动栏，隐藏活动栏的图标
• 活动栏图标可以拖动

侧边栏

侧边栏基本UI元素为可折叠视图，拖动可折叠视图可以调整顺序，右击可以隐藏视图

资源管理器

内置三个可折叠视图

• 打开的编辑器
• 文件夹
• 大纲

搜索

搜索视图可以实现多文件查找替换

源代码管理

支持对 git/svn 等代码仓库的管理

Run

运行/调试应用程序

扩展商店

管理扩展

编辑器组

编辑器可以细分为如下部分

• 标签 位于最上方的
• 快捷操作按钮 位于最上方右侧
• 编辑区域
• 最右侧的小地图和滚动条

面板

• 问题：展示各种Lint扩展检查出的问题信息
• 输出：展示扩展的输出，一般用于扩展调试
• 调试控制台：用于代码调试过程中查看变量等操作
• 终端：执行一些命令

状态栏

展示状态信息

命令面板

执行命令

在 VSCode 中所有操作都对应一个命令，触发这些命令的方式主要有两种

• 键盘快捷键
• 命令面板手动触发

唤起命令面板的默认快捷键为 command + shift + p

如何查看所有的命名呢，一个技巧就是打开快捷键配置视图进行搜索 （ command + shift + p 输入键盘 keyboard shortcuts 选择 首选项: 打开键盘快捷方式 ）

其他类型命令面板

VSCode 的命令面板以前缀来区分功能，具体可以通过如下方式列出

• ? 列出所有前缀，⌘P 并输入 ?

常用命令和快捷键

本部分仅列出常用的命令和默认快捷键，并提供命令名称，这样就可以在命令面板查看自己平台的快捷键和自定义配置快捷键

编辑器相关

光标移动

• 上下左右 方向键移动光标一个行/列
  • cursorUp
  • cursorDown
  • cursorLeft
  • cursorRight
• command+上下左右 光标移动到行尾行首列首列尾
  • cursorEnd
  • cursorHome
  • cursorTop
  • cursorBottom
• option+左右 光标移动一个单词
  • cursorWordStartLeft
  • cursorWordEndRight

选择

在光标移动的基础上多按住 shift 键

• command + a 选择全部
• control+shift+左右 根据代码语义进行选择与去取消
  • editor.action.smartSelect.shrink
  • editor.action.smartSelect.expand

多光标

• option+command+上下 在当前上面一行添加光标
• 一直添加光标到底部顶部
  • editor.action.addCursorsToBottom
  • editor.action.addCursorsToTop
• 根据单词匹配添加光标
  • 向下搜索 editor.action.addSelectionToNextFindMatch
  • 向上搜索 editor.action.addSelectionToPreviousFindMatch
• option + shift + i 在选中文文本的行尾部添加光标 editor.action.insertCursorAtEndOfEachLineSelected
• option + enter 在搜索窗口，选中命中的搜索目标

行操作

• 删除行 editor.action.deleteLines Eclipse 建议配置成 command + d
• option + 上下 整行移动
  • editor.action.moveLinesUpAction
  • editor.action.moveLinesDownAction
• option + shift + 上下 整行复制
  • editor.action.copyLinesUpAction
  • editor.action.copyLinesDownAction
• command + enter 在下方加入一行 editor.action.insertCursorAbove
• command + shift + enter 在上方加入一行 editor.action.insertLineBefore

智能编辑

• 智能提示（触发建议） editor.action.triggerSuggest Eclipse转来的用户建议配置成了 option + /
• command + / 切换注释 editor.action.commentLine
• shift + tab 去除缩进 outdent
• command + . 快速修复 editor.action.quickFix
• command + option + . 快速修复 editor.action.autoFix
• 显示悬停 editor.action.showHover，建议配置成 command + h（hover）
• command + F2 修改所有匹配项（相当于查找替换）
• 格式化文档，Eclipse 转来建议改成 ctrl+shift+f
  • editor.action.formatDocument 格式化整个文档
  • editor.action.formatSelection 格式化选中内容
• option + shift + o 组织导入 editor.action.organizeImports
• ctrl + shift + r 重构 editor.action.refactor
• editor.action.rename 重命名 editor.action.refactor

跳转

• F12 跳转到定义 editor.action.revealDefinition
• command + F12 跳转到实现 editor.action.goToImplementation
• shift + F12 转到引用 editor.action.goToReferences
• command + shift + \ 跳转到括号 editor.action.jumpToBracket
• F7 跳转到下一个匹配项 editor.action.wordHighlight.next
• shift + F7 跳转到上一个匹配项 editor.action.wordHighlight.prev
• F8 跳转到文件中下一个问题 editor.action.marker.nextInFiles
• shift + F8 跳转到文件中上一个问题 editor.action.marker.prevInFiles
• 符号跳转
  • command+t 搜索工作空间符号 workbench.action.showAllSymbols
  • shift+command+o 搜索文件符号 workbench.action.gotoSymbol
• 前进后退
  • workbench.action.navigateForward 前进 建议配置成 ctrl + =
  • workbench.action.navigateBack 后退 建议配置成 ctrl + -

折叠

• 全部折叠 editor.foldAll
• 全部展开 editor.unfoldAll

窗口切换

• command + n 新建文件窗口 workbench.action.files.newUntitledFile
• command + w 关闭窗口 workbench.action.closeWindow
• command + , 打开设置窗口 workbench.action.openSettings
• 编辑器窗口之间的切换
  • alt+cmd+right 下一个编辑器 workbench.action.nextEditor
  • alt+cmd+left 上一个编辑器 workbench.action.previousEditor
  • ctrl + tab 顺序切换 workbench.action.quickOpenPreviousRecentlyUsedEditorInGroup
• 编辑器与其他窗口切换
  • ctrl + 反引号 切换到终端 workbench.action.terminal.toggleTerminal
  • 切换到编辑器 workbench.action.focusActiveEditorGroup 建议配置成 option + e
  • command + shift + e 切换到资源管理器 workbench.view.explorer
• 终端
  • 新建终端 workbench.action.terminal.new 建议配置为 command + t
  • 上一个/下一个终端 workbench.action.terminal.focusPrevious 与 workbench.action.terminal.focusNext 建议配置为 command+option+上下

调试

• F5 启动调试/继续
  • workbench.action.debug.start
  • workbench.action.debug.continue
• shift + F5 停止调试 workbench.action.debug.stop
• F6 暂停 workbench.action.debug.pause
• command + shift + F5 重启调试 workbench.action.debug.restart
• ctrl + F5 运行，不调试 workbench.action.debug.run
• F10 单步跳过 workbench.action.debug.stepOver
• F11 单步进入 workbench.action.debug.stepInto
• shift + F11 单步跳出 workbench.action.debug.stepOut

终端相关

• command + k 清屏 (类似的有 clear 命令)
• ctrl + a 光标切换到行首
• ctrl + e 光标切换到行尾
• ctrl + u 或者 command + 退格 删除整行
• option + 退格 删除一个单词
• command + 上/下 滚动到上一条/下一条命令位置

配置

配置机制

使用 command + , 或者 command + shift + p 搜索 首选项 打开配置面板。

VSCode 的配置是基于文件的配置（格式为JSON，允许包含注释），有三个级别的配置优先级从高到低排序分别为：

• 工作空间配置 位于 .vscode/settings.json
• 用户配置 位于安装目录
• 默认配置

优先级高的配置覆盖优先级低的配置。当然VSCode提供可视化的配置页面，通过如下方式可以打开

使用 command + , 或者 command + shift + p 搜索 首选项 打开配置面板。

常见内置配置

本小结，将展示可能需要更改的配置。其他的配置建议保持默认即可

{
    "files.autoSave": false,  // 自动保存，建议不要开启，经常 command + s 是好习惯
    "editor.fontSize": 16,  // 建议开启老年人字体😂
    "editor.fontFamily": "consolas, Menlo, Monaco, 'Courier New', monospace, '文泉驿等宽微米黑'",  // 更换为自己喜欢的字体
    "editor.renderWhitespace": "all",  // 显示空格和Tab键
    "editor.codeActionsOnSave": [  // 如果是新项目建议开启，老项目建议关闭，保存时自动进行导入，自动修复
        "source.organizeImports",
        "source.fixAll",
    ],
    "editor.smoothScrolling": true,  // 炫酷的平滑滚动，在性能较好的设备中建议启用
    "editor.cursorSmoothCaretAnimation": true, //  炫酷的光标平滑滚动，在性能较好的设备中建议启用
    "editor.formatOnPaste": true,  // 建议开启，不满足 直接 command + z 撤销即可
    "editor.formatOnSave": true,  // 建议开启，保存自动格式化
    "editor.formatOnType": true,  // 建议开启，在回车后自动格式化
    "diffEditor.ignoreTrimWhitespace": false,  // 建议开启空白字符diff
    "editor.quickSuggestions": {  // 在所有位置输入所有字符都显示提示
        "other": true,
        "comments": true,
        "strings": true,
    },
    "files.exclude": {  // 建议显示 .git 文件
        "**/.git": false,
    },
    "files.insertFinalNewline": true,  // 在保存时，自动插入一行
    "workbench.editor.wrapTabs": true,  // 编辑器组标签溢出后自动换行
    "workbench.commandPalette.preserveInput": true,  // 再次打开命令面板恢复上次输入的内容
    "workbench.quickOpen.closeOnFocusLost": false,  // 失去焦点时，命令面板也不自动关闭
    "workbench.quickOpen.preserveInput": true,  // 再次打开快速打开板恢复上次输入的内容
    "workbench.colorTheme": "Monokai",  // 主题，在扩展商城挑选
    "workbench.iconTheme": "vscode-icons",  // 图标，在扩展商城挑选
    "breadcrumbs.enabled": true,  // 建议开启，是否显示编辑器顶部的导航路径
    "workbench.editor.tabSizing": "shrink",  // 编辑器 tab 紧凑模式
    "window.autoDetectColorScheme": false,  // 主题跟随系统变化
    "terminal.integrated.copyOnSelection": true,  // 将终端选中内容复制到剪切板
    "terminal.integrated.fontFamily": "Menlo, Monaco, 'Courier New', monospace,'Roboto Mono Medium for Powerline'",  // 配置终端字体
    "terminal.integrated.scrollback": 100000,  // 终端缓冲区大小，建议调大
    "terminal.integrated.shell.osx": "/bin/zsh",  // 配置 mac 的默认终端
    "terminal.integrated.shell.linux": "/bin/zsh",  // 配置 Linux 的默认终端
    "problems.showCurrentInStatus": true,  // 在状态连显示错误信息

}

扩展

以上部分仅介绍了 VSCode 的基本功能。VSCode真正强大之处在于他的扩展，因此一些优质扩展的安装是必不可少的。关于扩展相关内容，请参考

TODO 章节

更新时间：2020-04-04

目标

• 杜绝人员单点依赖风险（杜绝项目依赖特定个人，杜绝只有某个人才知道某个项目的关键点）
• 降低代码失控风险（降低代码千人千面情况）
• 快速入手（拥有开发能力的个人，可以短时间内，无需指点的自助进入开发状态）
• 代码整洁（让拥有代码洁癖的人，参与旧项目也有宾至如归的感觉）

原则

• code-repo-has-max-context 代码仓库拥有最大的上下文信息。该原则指，一个项目的全部信息（包括但不限于：PRD、部署信息、设计文档、测试、开发入门手册）可以通过代码仓库在明确的有限次跳后可以到达，不允许出现代码仓库无法触达信息孤岛
• develop-docs-all-in-code-repo 所有与开发相关的文档维护在代码仓库中（包括但不限于：系统设计文档、技术分享、开发环境搭建指南、开发规范）
• specification-by-tool-constraint 所有实施的规范必须通过工具进行约束，口头规范约束是无效的
• simple-local-run 代码仓库必须是可以在本地环境（个人电脑）根据文档在简单的配置后可运行的
• use-newest-lts-version 编程语言和依赖库使用最新的 lts 版本（或 stable），在新版本兼容性不足时或者生态受限时可以使用 latest - 1 版本
• not-dependent-specific-env 不依赖特定环境，所有依赖均可已通过 包管理工具（如 apt、mvn、pip）等安装；针对特定的没有被托管在包管理工具的依赖，必须放置与代码仓库中

开发环境规范

• 保证项目在 Mac 和 Linux 环境下可以正常开发，Windows 环境不考虑
• 不强制要求使用特定集成开发环境
• 不强制依赖某集成开发环境的特定功能
• 强制依赖cli环境的开发工具链

通用文件目录

• .gitignore
• **/.gitkeep
• cli/
• docs/
• README.md
• .editorconfig

git

约定使用 git 做代码版本管理工具，必须包含如下文件

• .gitignore 忽略文件
• **/.gitkeep 空目录建议添加一个 .gitkeep 文件以保证目录也被提交到 git 仓库中

cli

Shell 脚本，需要托管的二进制文件，等可执行文件放置于 cli 目录下，其目录结构如下

• cli/
  • cli/*.sh Shell 脚本
  • cli/lib/ Shell 脚本依赖的库，比如 jar 包等

docs

项目的各种文档，强制使用 markdown 格式进行编写，文档必须放在 markdown 目录下的二级目录下，命名格式为 %d%d.文件名.md，图片放置于 docs/asserts/images 目录下，一个例子如下：

• docs/
  • docs/asserts/images
  • docs/01.环境搭建/01.通用环境.md
  • docs/01.环境搭建/02.VSCode开发环境.md

README.md

项目梗概，同时可以包含 get started，非常重要，相当于项目主页

.editorconfig 等其他配置文件

• .editorconfig 是一种跨编辑器的通用文件格式配置文件，支持大多数主流编辑器和集成开发环境

分支管理与Devops

可以根据项目复杂度和人员规模进行选择，本规范采用单主干模式

• 一个主干分支
• 多个其他分支

准入流程（开发）

• 其他分支向 主干分支 提交 merge request 请求（下文简称 mr）
• （可选）准入工作流 拦截 该 mr，进入准入工作流
  • 进行代码规范检查
  • 单元测试
  • 功能测试
  • 以上各个阶段均成功后，进入下一阶段
• 邀请 Reviewer 进行 Review 和 合并

主干流程（上线）

• Merge 成功后进入 该流程（可选的每日定时集成）
  • 项目编译
  • 制作镜像
  • 基准测试
  • 人工卡点
  • K8S上线

P.S.

• 准入工作流需要在本地的 git hook 脚本 pre_commit 中进行配置

更新时间：2019-12-28

相关网站和公众号 * 上海市市民信息服务网 * 公众号：上海公安人口管理（shgarkb）

上海居住证用途

居住证是给外地人在上海享受社会公共福利的基本条件。

法规原文参见 《上海市居住证管理办法》（沪府令58号）

简单摘要如下几个作用（必备条件）：

参考： http://sh.bendibao.com/zffw/2018820/196865.shtm

• 办证
  • 护照（已经不需要了、可以选择全国通办）
  • 驾驶证
  • 参与沪牌拍卖资格（居住证满1年）
• 子女教育
  • 幼儿园、义务教育（小学初中）
  • 中考、高考、高中（积分120、不满无法参见）
• 子女社保（积分120）
• 子女公共卫生服务
  • 疫苗接种
• 资格评定、考试和鉴定

什么人需要上海居住证

想要在上海长期发展（一定要办）或者目前在上海但是未来没有规划的（以防万一）的在沪外地户口人员。

注意如果本科生或研究生通过积分落户的则不需要居住证（你已经是上海市民了）

办理流程和方式

居住证办理需要两个步骤，耗时半年。居住证办理下来后开可以办理居住证积分（委托单位办理）和居转户（7年），则不再本文讨论范围。

第一步：居住登记

居住登记需要跨部门办理，所以各个部门可能都不知道全部流程。且各个区也有可能不同，但是按照如下顺序办理，会省很多时间。当然也可以委托中介进行办理（可能会多花一些钱）。以下说明是个人办理的流程（亲身经历：宝山顾村公园附近）。

花费时间

• 实有人口信息采集 可能需要等待一段时间
• 其他步骤 一个上午搞定

各部门上班时间

• 居委会可能只有周一到周五上班
• 其他部门周一到周五上午8点30到下午16点30，节假日（周六日）只上午上班8点到11点半

居住登记的需要的材料和人

• 人员
  • 房东
  • 租客
• 材料
  • 房东的房屋所有权证/上海市房地产权证/不动产权证
  • 房东的身份证
  • 房客的身份证

注意：

• 此处只陈述租房场景的
• 房产证的如果有多人所有人都要到场或者至少来一个（需要其他人写一个委托书、非本人经历不一定可行）
  • https://wenku.baidu.com/view/4872c7d5bf23482fb4daa58da0116c175e0e1e68.html
• 申请表等各个部门都有不要自己打印
• 材料复印件可以准备一份，各个部门也可以打印
• 如果是二房东的话或者房东不愿意给你办或者房东没有房产证等证件的话，你可以按如下办法做
  • 找房产中介（不限于自己租的房子的中介）说明花钱办理居住证
  • 如果自己有亲戚朋友在上海有房产，那么可以麻烦亲戚朋友按照如下步骤走（个人做法）

居委会

居委会一般每个小区都有一个，一定要先到居委会去。

到居委会后告诉工作人员你要办居住证，他会给你做 实有人口信息采集（拍照、上传身份证、居住地址），这些信息会上传到公安系统。工作人员会告诉你几天后可以去办居住证了，接下来的地点也会和你说的（或者问他），以前需要领个证明材料现在已经不需要了。

这一步骤自己去就行了。

居住证受理网点1

全部网点如下：

https://www.962222.net/pages/sbk/sbkfw.html

一般是社区受理中心（也可能是公安局，和社区受理中心不再一个地方），先到这里来的原因是需要问明你签的合同的房租是多少，他们需要收房屋租赁税，为了创收他们不允许你的合同租金过低。

所以该步骤就是咨询

告诉工作人员你要办理居住证，他会告诉你却什么材料，一般是《房租赁合同通知书》，并咨询清楚房屋房租应该是多少。并问清楚去哪里办《房租赁合同备案通知书》。

需要和房东一起携带上述材料前往

社区受理中心

地址： 地图应用搜 社区受理中心

告诉工作人员要办理居住证，他会现场给你办理网签（租赁合同网签备案，原来需要跑房产中心的，2019-12-26日起在社区受理中心就可以一站式办理了🎉）（填写申请表，注意房租金额，签约时间，建议长一点比如3年，省得再跑一遍），然后出具一个《房租赁合同备案通知书》。

最后询问后续步骤的地点（再次确认流程）

居住证受理网点2

注意这一步可以尝试在网上办理通过《上海公安人口管理》公众号进行办理（本文未尝试过，不知道是否可以跳过交税）

回到此处，他会审查你的材料，并可能让你去交房屋租赁税（2019-12-27房租税率为2.5%）。然后填写材料拍照，给你一个《居住登记凭证》

至此居住登记办理完成。

注意&后续

• 半年内不要变更《实有人口信息申报》，否则无法办理居住证
  • 在这半年内，如果换房子了，房东大概率会向你要身份证时，这时候和他说明你在班居住证，不能让他去给你登记。
  • 即使被登记了，也没关系，按照如下步骤操作：
    • 关注微信公众号：上海公安人口管理（shgarkb）
    • 选择：业务办理 -> 业务办理
    • 点击：实有人口信息自助申报，重新填写会之前登记的地址区县
    • 一般不会有人电话核实
    • 等待3个工作日，公众号推送“业务办理公知”状态为“已采集”即可
• 妥善保管好
  • 《房租赁合同备案通知书》
  • 《居住登记凭证》
• 税款仅支持现金支付
• 定好闹钟日程，半年后申领居住证

第二步：申领居住证

申请

• 时间：居住登记半年后
• 地点：居住证受理网点
  • 工作时间：工作日8:30~16:30，周末8:30~11:30
• 准备好如下材料
  • 税单
  • 《上海市住房租赁合同备案通知书》
  • 《居住登记凭证》
  • 办证者本人身份证
  • 零钱/身份证复印件
• 到场人员
  • 办证者本人
  • 深色上衣（可以重新拍摄居住证证件照片）
• 耗费时间：10分钟内

回执材料

• 《上海市居住证受理回执》

领取

• 时间：申请后20天
• 地点：居住证受理网点
  • 工作时间：工作日8:30~16:30，周末8:30~11:30
• 准备好如下材料
  • 《上海市居住证受理回执》
• 到场人员
  • 办证者本人
• 耗费时间：5分钟内

您构建的网站的默认Hugo输出目录是 public/。但是，您可以通过在 站点配置 中指定其他publishDir来更改此值。在构建时为节创建的目录反映了内容文件夹中内容目录的位置以及与contentdir层次结构中的布局匹配的命名空间。

站点配置 中的 permalinks 选项允许您基于每个部分调整目录路径（即URL）。这将更改文件写入的位置，并将更改页面的内部“规范”位置，以便对 .RelPermalink 的模板引用将遵循由此选项中的映射所做的调整。

这些示例使用publishDir和contentDir的默认值；即，分别是 public 和 content。您可以覆盖 站点配置文件 中的默认值。

例如，如果您的某个 sections 被称为帖子，并且您希望根据年份，月份和帖子标题将规范路径调整为分层，则可以分别在YAML和TOML中设置以下配置。

永久链接配置示例

[permalinks]
  posts = "/:year/:month/:title/"

只有 posts/ 下的内容才会有新的URL结构。例如，文件内容 /posts/ sample-entry.md 中 front matter 的data为：2017-02-27T19:20:00-05:00，则这个内容在构建中将渲染到 public/2017/02/ sample-entry/index.html 中，因此可以通过https://example.com/2017/02/sample-entry/访问。

您还可以使用相同的语法配置按照分类来配置的永久链接来取代默认的section，您可能只想使用配置值 :slug 或 :title。

永久链接配置值

以下是可在站点配置文件中的permalink定义中使用的值列表。所有对时间的引用都取决于内容的日期。

:year

4位年

:month

2位月

:monthname

英文月

:day

2位天

:weekday

1位周 (Sunday = 0)

:weekdayname

英文周

:yearday

1到3位，今年中的第几天

:section

所在目录

:sections

content到文件所有层次的目录

:title

内容标题

:slug

内容的slug

:filename

文件名不带扩展名

别名

别名可用于从其他URL创建重定向到您的页面。别名有两种形式：

• 以/开头，表示相对于BaseURL，例如 /posts/my-blogpost/
• 相对路径，相对于这个Page，例如../blog/my-blogpost Hugo 0.55 新增

别名的例子

假设您在 content/posts/my-awesome-blog-post.md 中创建了一段新内容。该内容是您在 previous/posts/my-original-url.md 上发布的上一篇文章的修订版。您可以在新 my-awesome-blog-post.md 的 front matter 中创建别名字段，您可以在其中添加以前的路径。以下示例分别显示如何在TOML和YAML前端内容中创建此字段。

+++
aliases = [
    "/posts/my-original-url/",
    "/2010/01/01/even-earlier-url.html"
]
+++

---
aliases:
    - /posts/my-original-url/
    - /2010/01/01/even-earlier-url.html
---

现在，当您访问别名中指定的任何位置时，即假设相同的站点域 —— 您将被重定向到指定的页面。例如，example.com/posts/my-original-url/ 的访问者将立即重定向到example.com/posts/my-awesome-post/。

多语言中的别名的例子

在 多语言网站 上，帖子的每个翻译都可以有唯一的别名。要在多种语言中使用相同的别名，请在其前面加上语言代码。在/posts/my-new-post.es.md中：

在/posts/my-new-post.es.md中：

---
aliases:
    - /es/posts/my-original-post/
---

从Hugo 0.55其，你也可以有页面相对别名，所以/es/posts/my-original-post/可以简化为更便携的 my-original-post/

Hugo别名如何运作

指定别名时，Hugo会创建一个与别名条目匹配的目录。在目录中，Hugo创建了一个.html文件，指定页面的规范URL和新的重定向目标。

例如，posts/my-intended-url.md 中的内容文件，front matter有以下内容：

---
title: My New post
aliases: [/posts/my-old-url/]
---

假设example.com为baseURL，在https://example.com/posts/my-old-url/上找到的自动生成的别名.html的内容将包含以下内容：

<!DOCTYPE html>
<html>
  <head>
    <title>https://example.com/posts/my-intended-url</title>
    <link rel="canonical" href="https://example.com/posts/my-intended-url"/>
    <meta name="robots" content="noindex">
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <meta http-equiv="refresh" content="0; url=https://example.com/posts/my-intended-url"/>
  </head>
</html>

http-equiv="refresh"是执行重定向的代码，在这种情况下为0秒。如果您网站的最终用户访问https://example.com/posts/my-old-url，他们现在会自动重定向到更新，更正确的网址。添加<meta name ="robots" content ="noindex">可让搜索引擎机器人知道他们不应抓取您的新别名页并将其编入索引。

自定义

您可以通过在站点的layouts文件夹中创建alias.html模板来自定义此别名页面（即layouts/alias.html）。在这种情况下，传递给模板的数据是：

Permalink

指向别名的页面的链接

Page

该别名指向的页面的数据

别名的重要行为

• hugo对别名没有任何假设。它们也不会根据您的UglyURL设置进行更改。您需要提供Web根目录的完整路径以及完整的文件名或目录。
• 别名在渲染任何其他内容之前渲染，因此将被具有相同位置的任何内容覆盖。

该文档处于设想阶段，并未落地实践

参考

• Rust RFC 项目管理调研

简介

RFC 全称 （Request for Comments），征求意见。

RFC 概念最早在 互联网 标准指定领域出现。在互联网技术标准领域，RFC 是技术标准文档的代名词，业界公认的主流的互联网技术，比如 TCP/IP 都编入了 IETF 的 RFC 文档中。换句话说，想成为互联网技术方面的标准或者基础设施，都需要进入 IETF 的 RFC 文档

在开源技术领域，古老的开源项目，比如 Linux，采用的是 邮件组的 方式来进行讨论及项目管理。

较新的开源项目，会考虑使用 Github + RFC + IM/论坛 机制来实现 Feature 管理。比如 Rust、React。

关于 Github 和 mail list 参见：博客

RFC 内容

参考：Rust RFC 项目管理调研 / 模板

开源项目的 RFC 使用姿势

开源项目的特点

• 任何人都可以贡献代码
• 贡献者间不熟悉，来自全球各地

开源项目贡献者角色分析

• 意愿贡献者，想为开源项目贡献代码，但是还没有贡献（多数）
• 普通贡献者，偶尔为开源项目贡献代码
• 项目组核心成员，经常为项目贡献代码，同时负责开源项目管理，参与技术讨论，决策

开源项目管理的诉求

• 新人能更容易的参与到迭代中
• 核心成员对项目的迭代方向、代码质量有控制力

开源项目 RFC 的基本流程

物料准备

• rfc 仓库，用来维护所有的 rfc 文档
• rfc 仓库 PR 讨论区，作为 rfc 设计评审的讨论地点
• 项目代码库
• 项目代码库代码库的 Issue 讨论区，作为该 rfc 实现过程的讨论地点

角色（一人可能身兼数职）

• 核心项目组成员
• rfc 作者
• rfc 实现者

RFC 创建、讨论、评审流程（工作在 rfc 仓库）

• 确认如下问题
  • 查看所有历史 RFC，确认待创建的 RFC 不存在或者没有被拒绝
  • 该 Feature 不是 Bugfix、重构类的需求
• Fork 代码库，根据模板编写 RFC
• 提交 PR
• 初步评审，项目组核心成员对该 RFC 质量，是否有重复等问题，决定是否进入下一阶段
• 讨论阶段，相关利益相关方在此 PR 处进行讨论，作者根据讨论进行修改并 commit。讨论参与者如下
  • RFC 作者
  • 相关项目组核心成员
  • 所有感兴趣的其他人员
• 最终动议阶段，RFC 作者 和 相关项目组核心成员认为可以进入最终动议阶段，则可以发起最终动议，公示一段时间后，没有问题，则激活 RFC。同时 该 RFC 的 PR 将合入 RFC 仓库

RFC 开发阶段（工作在 项目代码库）

• 在项目代码库创建一个 Issue 用来追踪 RFC 的实现情况
• 实现者（当然欢迎 RFC 作者作为实现者）认领该任务，进入开发阶段

商业项目管理 结合 RFC 机制

商业项目的特点

与开源项目不同，商业项目

• 研发成员相互之间在同一地点办公，彼此熟悉
• 能参与讨论的成员相对较少，核心开发一般较少
• 存在 PM 、测试 角色，分工更细，需求一般偏业务
• 迭代速度要求尽量快，代码质量要求相对迭代速度优先级低一些

流程设计

仅设想阶段

使用 RFC 管理 需求

• 参考 Rust RFC 项目管理调研 / 模板 给出 RFC 模板，该模板需要按照业务类型需求重新设计，主要包含 PRD、 技术方案、测试验收方案的内容
• 一个 RFC 一般需要三种角色
  • PM
  • 技术（两人）
  • 测试
• RFC 文档 可以使用公司内部的 在线 Doc 平台 （需附上 IM 群） 或者 Gitlab （推荐） 中编写，使用标签或者在文章中添加状态或者使用需求管理软件管理状态，来管理 RFC 生命周期
• RFC 评审
  • 评审的形式不一定是会议，可以是评论、论坛、群聊的方式
  • 一般有两次：产品方案评审、技术方案评审
  • 更新 RFC 的状态
• 开发阶段
  • 更新 RFC 的状态，并添加一个 Issue 的链接
  • 使用 Issue 管理 RFC 的实现，在描述上关联上 RFC 的链接
  • Gitlab 的多个 MR 上关联上 Issue，一个技术提交必须要另外的一个技术的 Review
• 验收阶段，测试进行测试，验收阶段结束后，关闭 Issue，更新 RFC 状态，并最后校验文档和实现是否脱节

优缺点

优点

• 更标准化的管理方案文档和代码实现以及两者相互索引，提高项目质量
• 因为存在众多 RFC 文档，且 RFC 文档的讨论和 MR 或者 PR 都有管理，所以新人更容易快速进入状态，了解历史进度
• 扩大所有人对项目的 context 的了解，不至于出现人员点单，降低人员变更带来的风险
• 方案指导开发，给开发人员一种普遍的方案设计思路，提高开发人员的核心素质，培养开发人员工程师思维（做 Engineer、Developer 摆脱 coder）

缺点

• 部分程序员无法将设计和开发彻底分离，设计后置到开发阶段，也就是说该这种程序员在设计阶段的想法无法落实在开发上。这将导致
  • 存在阵痛期，认为写 RFC 是浪费时间，心理上会有抵触情绪
  • 产出的 RFC 和代码不符，导致 RFC 文档反而误导其他成员
  • 需要要求开发者有 Owner 精神
• 一定程度降低迭代速度

VSCode 基本页面布局目前无法通过扩展进行定制，但是官方提供了两种主题定制机制

• 颜色主题，可以定制定制
  • 页面各个部分的颜色
  • 编辑器各种语法高亮的颜色
• 图标主题
  • 定制各种文件的图标样式

以上这些主题可以通过 商店 进行安装

颜色主题

切换方式

打开命令面板 >Color Theme 即可进行颜色主题切换

流行的颜色主题

• Monokai Dark Soda
• Night Owl
• One Dark Pro
• One Monokai Theme

图标主题

切换方式

打开命令面板 >File Icon Theme 即可进行颜色主题切换

流行的图标主题

• Material Icon Theme
• vscode-icons
• Material Theme Icons

Better Comments

Better Comments 是一个美化注释颜色的扩展，原生的注释的描述性文字颜色比较单一，而该扩展作用是根据特殊某些规则给注释文字染色以达到突出显示和美化的效果。内置5种高亮例子如下：

/**
 * 正常注释
 * * 重要信息高亮
 * ! 危险信息提示
 * ? 疑问和不确定
 * TODO TODO 信息
 * // 被删除的注释
 */
class App {

}

该扩展同样支持通过 配置自定义颜色效果

{
    "better-comments.tags":   {
        "tag": "!",
        "color": "#FF2D00",
        "strikethrough": false,
        "backgroundColor": "transparent"
    }
}

Bracket Pair Colorizer 2

Bracket Pair Colorizer 2 是一个对括号匹配高亮的扩展，可以让我们一眼识别括号匹配情况。之前有一个V1的版本，V2版本提升了性能。

参考文章

• 从 VSCode 看大型 IDE 技术架构
• VSCode技术揭秘

基本情况

代码仓库

https://github.com/microsoft/vscode

技术栈

• 采用了 基于 Chromium 的 Electron 框架（JavaScript，HTML 和 CSS 构建跨平台的桌面应用程序）
• 编程语言上采用微软自家的 TypeScript （JavaScript 的超集，有类型，与JavaScript互操作兼容）
• 编辑器UI上采用 Monaco

定位

位于 IDE 和 轻量级编辑器之间。更加偏向 编辑器 一侧。其核心是 编辑器 + 代码理解 + 调试。围绕这个关键路径做深做透，其他东西非常克制，产品保持轻量与高性能。

进程架构

多进程架构。（可以通过帮助菜单 -> 打开进程管理器 查看，可以看到进程的父子关系等信息）

• 主进程：VSCode 的入口进程，负责一些类似窗口管理、进程间通信、自动更新等全局任务
• 渲染进程：负责一个 Web 页面的渲染
• 扩展宿主进程：扩展运行在 独立的扩展宿主进程中，不允许访问 UI
• Debug 进程：Debugger 相比普通扩展做了特殊化
• Search 进程：搜索是一类计算密集型的任务，单开进程保证软件整体体验与性能

VSCode 采用松散的架构，模块间的耦合很小。

扩展机制

• 扩展API 相对克制，仅暴露核心 API，不暴露编辑器 DOM UI，提供有限的 UI 组件API，这样做的好处
  • 对于扩展来说基本够用
  • 对于VSCode内核来说可以从容重构，不会太多受到扩展API的牵制
  • 对于用户来说，始终有统一的UI交互风格，降低心智成本
• 扩展与 编辑器 核心强隔离，耦合程度小，扩展运行在对立的扩展进程中，扩展API与内核通信的通过RPC服务进行
  • 保持编辑器的性能不受 扩展的影响
  • 为 Remote Develop 打下基础
• 不同编程语言的支持，通过语言服务器协议（LSP）实现，扩展和语言服务器之间通过 JSON PRC 进行通信
  • 更好的复用其他语言开发的相关工具
  • 保持开放，使一个语言服务器可以支持多种编辑器/开发环境

更新时间： 2020-04-04

本文可能疏于更新：最新情况请参考 Github Repo

前置文章：通用规范

版本选择与依赖管理

主编程语言Java

维基百科: Java Version History

选择 目前 Java 最新的 TLS 版本 Java11 （发布于 2018 年 9 月，下一个 Java TLS 版本为 Java17，预计于 2021 年 9 月发布）

相关 SDK 安装( SDKMAN 方式 )

curl -s "https://get.sdkman.io" | bash
# 重新打开终端
# 如果你的系统安装了Java，最好该Java交由SDK管理
sdk install java 8.0.191-local $JAVA_HOME
sdk install java 11.0.6.hs-adpt
# 仅当前shell生效
sdk use java 11.0.6.hs-adpt
sdk default java 11.0.6.hs-adpt
# 恢复 java8
# sdk default java 8.0.191-local
java -version

Spring Boot

采用 最新的 2.2.6.RELEASE 版本

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot</artifactId>
    <version>2.2.6.RELEASE</version>
</dependency>

依赖管理

• 使用分模块的Maven项目
• 被大于一个模块使用过的依赖在根 pom.xml 中的 dependencyManagement 进行版本管理

Maven Wrapper

为方便构建镜像，应使用 ./mvnw 命令替代 mvn 命令，创建方式

mvn -N io.takari:maven:wrapper

将创建如文件和目录

• .mvn/
• mvnw
• mvnw.cmd

模块设计

依赖关系

template-dto        template-scala
    ^                ^
    |                |
    ------------------
            |
        template-core
            ^
            |
    ------------------
    |                |
template-web        template-batch

• template-web 负责提供web服务，主要包含如下模块
  • controller
  • config
  • filter
  • security
  • utils
• template-batch 负责执行某些定时/异步任务
• template-core 核心业务逻辑，主要包含如下模块（细节参见 阿里Java开发手册）
  • DO
  • BO
  • DAO
  • Service
• template-dto 数据传输对象，service层的参数与返回值，单独抽出来的原因是该部分可能被复用，比如
  • OpenAPI 的 Client
  • RPC 的 Client
• template-scala 可选，当与其他 JVM 语言交互式，建议独立出一个模块

编码规范

以如下两个规范作为蓝本，根据情况进行定制化的选择

• 阿里Java开发手册
• Google Java Style 指南

将结果配置到配置文件中，并在如下两个地方应用配置

• 配置 Maven Plugin 进行检查，调用 mvn verify 进行检查，该部分参见脚本管理
  • 应用在 .git/hooks/pre_commit 在提交之前进行严格的规范检查
  • 应用在 准入工作流
• 配置集成开发环境插件，进行实时检查

规范检查

./cli/verify.sh

配置方式参见：Java 代码样式检查落地

文档设计

• README.md
• docs/01.环境搭建
• docs/02.规范约定
• docs/03.技术方案
• docs/04.模块设计

脚本管理

• ./cli/verify.sh CI 的 代码规范检查 步骤
• ./cli/unit_test.sh CI 的 单元测试 步骤
• ./cli/build.sh 构建二进制包
• ./cli/pre_commit 为 .git/hooks/pre_commit 软链或者调用的脚本

数据库migrations

所有数据库版本脚本均托管到 git 仓库中，建议手动管理（因为企业级系统一般均有DBA进行限制DDL操作），目录位于 template-core/src/main/resources/db/migrations 目录。

该目录下包含多个目录，每个目录就是一个数据库变更版本，这些目录的命名方式为 YYYY-mm-DD-%d%d%d%d%d%d-name，每个目录下包含两个文件 up.sql 和 down.sql（可选）如下

• 2020-04-02-000000-init
  • up.sql
• 2020-04-02-000001-new-core
  • up.sql

配置管理

配置文件约定

• 格式统一为 *.yml，语法参见 https://www.ruanyifeng.com/blog/2016/07/yaml.html
• 线上环境命名规则为 application-prod-$region.yml，例如
  • application-prod-cn.yml
  • application-prod-jp.yml
• 个人开发环境命名规则为 application-dev-$username.yml
• 所有自定义配置项在 application.yml 中有默认值
• 配置文件仅允许出现在 template-web 和 template-batch 模块下

配置项约定

所有自定义配置项（非框架配置项，都定义在 template 域的一个子域）

template:
    region: cn
    xxx:
        id: xxx
        key: xxx

配置项禁止直接通过 @Value 注入，通过 template-core 下的 TemplateConfiguration 类 访问配置，该类添加 @ConfigurationProperties(prefix = "template") 注解；对于其他子域也创建相关类，并作为 TemplateConfiguration 的成员。

更新时间：2020-04-04

Leader安排下来的事项

利益相关

• Leader 不关系你是如何实现的，他们一般只看结果
• 团队成员配合你的工作对于他来说没有太大收益，只是一种义务
• 个人作为一个承上启下的作用
• Context 方面
  • 在做这件事情的原因和背景方面 Leader > 个人 > 其他成员
  • 在具体落实方案和实施后的收益方面 个人 > 其他成员 > Leader

明确事项

当 Leader 给你分配这件事情的时候，他一般只会告诉你要目标是什么，但是由于信息偏差，他可能不会告诉你为什么做这件事情（这件事情的背景）。因此，在你给出具体实施方案之前，一定要向 Leader 明确如下事项：

• 这件事项完成后如何评估收益，是否可以量化？
• 为什么要做这件是，背景是什么？
• 如果是一线 Leader，他应该有更多的经验，可以询问下做这件事情的有没有什么推荐的实施手段

实施计划

制定实施方案的时候，需要注意如下事项

• 明确背景/目标，让大家思想上达成一致和认可
• 如果需要成员讨论决策的话，作为实施负责人
  • 事先必须给出方案（因为其他成员没有义务帮你出主意），让大家在这个草案的范围内进行讨论，否则讨论可能会变成太过于发散
  • 制定方案的之后，在讨论之前，最好交给 Leader 和 团队核心成员（经验丰富者） Review，确认方案可行性和改进点，这样可以避免在由于个人经验不足导致方案不足，在会议中被 Challenge 甚至 Diss
• 方案必须具有简单性和可操作性，主要体现在两个方面
  • 需要你做的部分技术上可行，且不会很复杂，这样可以节省你的时间，做更有意义的事情
  • 需要其他成员做的部分尽量的少，尽量的简化；否则大家都有自己要忙的事情，会很不情愿做你推动的事情
    • 不要给成员太多自由的选择和决策的可能性，如果这样，大家会倾向于按自己的利益方向进行考量，可能无法完成设定的目标
    • 建议给一个在大家能忍受的，对达成目标方向最优的默认值，这样才能掌握主动
• 确保方案可以达到 Leader 的目标，在这个阶段必须考虑如何量化工作成果
• 一定要明确方案 Deadline，且 Deadline 的指定一定要留有余地，否则自己会很被动
• 方案一定要文档化，表格化，不能只停留在脑子中

如何更好的推动方案的实施

• 最好的方式是在，会议上提出这件事情，描述清楚事情的背景，简述下方案的重点，将方案文档发给大家。并让 Leader 发言强调下事情的重要性，同样做如下的事情
• 其次的方式是，建立一个IM群组，@Leader @所有人，然后比较正式的发出一个消息，文字控制在100字内，大概格式如下
  • 标题
  • 背景
  • 需要大家做的事情
  • 影响/收益
  • Deadline
  • 附件：方案文档/表格/其他资源链接
• 每天发送下大家的处理进度和距离 Deadline 的时间
• 在接近 Deadline 的时候单独找 进度缓慢的成员聊下，让他关注下这个事情

收尾

• 统计收益，并将收益文档化，且有数据支撑
• 将收益，发送给 Leader 和 团队成员，并 感谢大家的 付出

个人的想法

比如想在团队中推动某些流程的标准化，推动某些机制等

TODO

如果熟悉 git 命令，使用命令操作可能更高效且知识的迁移性更高。

另一方面，以下扩展如果熟练使用的话可能更直观快捷，如下扩展在功能上可能存在重复，可以对比选择使用。

Git Graph

Git Graph 专注于可视化 git 的 分支图。通过该扩展可以直观的看到分支合并情况，代码变更与比较

使用方式

• 通过 >git graph: View Git Graph 命令
• 通过 状态栏 的 Git Graph 按钮

GitHub Pull Requests and Issue

GitHub Pull Requests and Issues 微软 Github 官方的 Github 管理工具，用于托管在 Github 上的 项目的工作流管理。

GitLab Workflow

GitLab Workflow

类似于 GitHub Pull Requests and Issue 扩展。

Gitlab 一般用于企业级 项目管理，因此此扩展在日常搬砖过程中非常有用。

基本配置

• 前往 profile/personal_access_tokens 页面生成 Token 勾选如下权限，然后点击生成，然后复制备用
  • api
  • read_user
• 打开 VSCode，输入 命令 >GitLab: Set GitLab Personal Access Token
  • 首先输入 Gitlab 的首页
  • 然后输入 粘贴 刚刚复制的 token

如果是私有部署的Gitlab，需要在设置中配置

{
    "gitlab.instanceUrl": "https://my-gitlab-domain.com"
}

功能

• 状态栏显示流水线/MR数目和基本状态
• 活动栏查看 Issue / MR 列表
• 一些命令，通过 >Gitlab: 前缀可以查看，这里展示几个常用的
  • >gitlab create snippet 快速创建 代码片段
  • >gitlab create new issue on current project 快速打开创建 issue 页面
  • >gitlab create new merge request on current project 快速为当前分支创建 MR
  • >gitlab open 快速打开系列

Git History

Git History

类似于 Git Graph，可以通过 命令 > Git: View History 打开，或者通过 源代码管理 侧边栏的标题上的图标进入

Project Manager

Project Manager

工作空间管理，在项目非常多的情况可以使用。类似于项目收藏夹的功能，可以快速一键打开项目。具体功能如下

• 通过 > Project Manager: 前缀 可以列出所有命令列表
• 提供一个侧边栏，通过活动栏的按钮打开侧边栏

• 项目管理主要通过JSON配置文件的方式进行管理，可以通过 >project manager: edit projects 打开

  • 目前仅 name, rootPath, and enabled 字段被使用

  • $home 将会替换为用户家目录

    {
    "name": "Numbered Bookmarks",
    "rootPath": "$home\\Documents\\GitHub\\vscode-numbered-bookmarks",
    "paths": [],
    "group": "",
    "enabled": true
    }

GitLens — Git supercharged

GitLens — Git supercharged

GitLens 功能十分强大，基本特性如下

• 在当前行尾以浅色字体显示
  • 当前行的作者，最后提交时间，提交消息
• 在文件头部显示作者，最新更新时间，点击作者可以打开 File blame annotation 视图
• 提供一个功能丰富的侧边栏
  • 代码仓库视图
  • 文件历史视图
  • 行历史视图
  • 自定义搜索视图
  • 比较视图
• 👍File blame annotation 视图，展示文件每一行的提交信息
  • 通过 >gitlens.toggleFileBlame 命令或者左上角 图标打开
• 👍文件热度图
  • 通过 >gitlens.toggleFileHeatmap 命令打开
  • 通过 "gitlens.heatmap.toggleMode": "window" 配置命令适用于整个窗口
• 👍高亮显示当前文件最后一次更改内容
  • 通过 >gitlens.toggleFileRecentChanges 命令打开
  • 通过 "gitlens.recentChanges.toggleMode": "window" 配置命令适用于整个窗口

配置说明： https://github.com/eamodio/vscode-gitlens#gitlens-settings-

gitignore

gitignore

一个很有用的小扩展，根据类型给你的 项目添加 gitignore >add gitignore

Open in GitHub, Bitbucket, Gitlab, VisualStudio.com

Open in GitHub, Bitbucket, Gitlab, VisualStudio.com !

通过 命令 > open in 快速打开当前文件在 github 类网站的页面

相关 context

• 运行环境：VScode 内部 Electron 依赖的 Node 版本
• 开发语言：TypeScript （官方推荐）、JavaScript 等
• 开发环境：VSCode
• 语言服务器LSP：支持任意编程语言

创建

VSCode 官方提供了 相关的 yo 模板，安装

# 安装模板生成器
npm install -g yo generator-code
yo code

开发调试

为了调试时启动速度，建议修改调试配置 .vscode/launch.json，添加 "--disable-extensions" 启动参数

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Run Extension",
			"type": "extensionHost",
			"request": "launch",
			"runtimeExecutable": "${execPath}",
			"args": [
				"--disable-extensions",
				"--extensionDevelopmentPath=${workspaceFolder}"
			],
			"outFiles": [
				"${workspaceFolder}/out/**/*.js"
			],
			"preLaunchTask": "${defaultBuildTask}"
        },
    ]
}

发布

方案

• 粒度：双月级/日级别
• 每双月初指定双月OKR（借公司系统）
• 每天指定当天计划
  • 前一天晚上/当天早上，将前一天未完成的任务放置到当天计划中，并将当天新的任务添加到计划中
  • 按照优先级排序
  • 没完成一项后勾选掉
  • 依次循环

失控

• 初期，任务较简单，时间周期较短，每天任务不超过10行
• 2020年起，逐步失控，非重要任务开始挤压，每日任务列表开始膨胀（膨胀到64行），导致
  • 无法一眼看清楚要做什么，非常不明确，等于没有计划
  • 低优任务得不到调度

2020-04-07

方案

• 粒度：双月级别/周级别/日级别
• 每双月初指定双月OKR（借公司系统）
• 每周制定当周的任务清单
  • 每周日/周一，将上周未完成的任务搬移到本周任务中
  • 当周有新增任务，添加到当周的任务列表中
  • 当周每完成一项任务，将该任务标记为已完成
  • 依次循环
• 每天制定和实施当天计划
  • 前一天晚上/当天早上，从周任务清单中抽取每个大项中的子项目到当天计划中，需要注意
    • 任务数目视当天时间情况进行评估（避免无法完成）
    • 要保持 低优任务 可以得到调度，避免饥饿（低优任务得不到实施）
  • 当天每完成一项任务，将该任务标记为已完成，同时将对应的周任务项目标记为完成

更新时间：2020-04-04 本文可能疏于更新：最新情况请参考 Github Repo

推荐等级

• 必备：如果从事该类别的工作，该扩展应该是必备扩展，使用该扩展可以极大的提高效率
• 推荐：建议安装，锦上添花，不适用也不影响效率
• 知悉：告知存在此类扩展，使用与否视情况而定

远程开发

远程开发是 VSCode 最重大的特性，是其最具有竞争力的地方。因此，在推荐列表的第一部分，详细参见： 优质扩展/远程开发

语言包与翻译

VSCode 的国际化支持是通过语言包扩展实现的，同时商店中有一个辅助翻译的扩展以帮助大家阅读英文注释和变量命名的含义

说明

• 更多语言包参见 扩展商店
• 语言切换方式 >configure display language
• Comment Translate 的使用方式：鼠标选中需要翻译的文本上，针对注释，直接放置在注释上即可
  • 命令前缀 >Comment Translate:
  • 快速选择 目标语言，点击状态栏的地球图标

来自其他编辑器

如果真心想将 VSCode 作为开发主力，建议还是接受 VSCode 的快捷键逻辑；针对部分是在用惯的快捷键，可以通过 快捷键配置 来进行 自定义。最好不要使用如下扩展，全部映射。

更多快捷键绑定参见： 商店

关于 VIM 扩展的额外说明：

• 特有命令
  • gd 相当于vim中的ctrl+] 跳转到定义
  • gb 多光标模式，找到下一个和当前单词匹配的单词并添加光标
  • gh 显示当前位置的悬浮提示框
• 打通系统剪切板 配置 “vim.useSystemClipboard”: true,`

• 输入法

  • 安装 im-select *MAC 安装 curl -Ls https://raw.githubusercontent.com/daipeihust/im-select/master/install_mac.sh | sh

  • 配置如下（中文）

    {
    "vim.autoSwitchInputMethod.defaultIM": "com.apple.keylayout.ABC",
    "vim.autoSwitchInputMethod.obtainIMCmd": "/usr/local/bin/im-select",
    "vim.autoSwitchInputMethod.switchIMCmd": "/usr/local/bin/im-select {im}",
    "vim.autoSwitchInputMethod.enable": true,
    }

美化

详细参见： 优质扩展/美化

Git和工作流

详细参见： 优质扩展/Git和工作流

通用

• Bookmarks
• Code Runner
• Code Spell Checker
• Comment Translate
• EditorConfig for VS Code
• i18n Ally
• LeetCode
• New File by Type
• Open in GitHub, Bitbucket, Gitlab, VisualStudio.com !
• Path Intellisense
• Project Manager
• REST Client
• SonarLint
• Settings Sync
• TabNine
• TODO Highlight
• Todo Tree
• Visual Studio IntelliCode
• CodeQL
• Reference Search View
• Archiver
• Zip Preview

SQL

• SQLTools - Database tools
• PostgreSQL

协作

• CodeTour
• CodeStream
• Live Share
• Live Share Audio

Docker&K8S

• Docker Extension Pack
• Kubernetes
• Docker Explorer

服务提供商

• Travis CI Status
• Salesforce CLI Integration
• Azure Account
• Cloudfoundry Manifest YML Support
• Concourse CI Pipeline Editor
• Spark & Hive Tools
• Azure Virtual Machines
• Azure CLI Tools

Web前端开发&NodeJS

• Debugger for Chrome
• ESLint
• JavaScript Booster
• npm
• npm Intellisense
• open in browser
• TSLint
• yo
• Node Debug

C/C++

• C/C++

Java

• Java P3C Checker
• Java Properties
• Java Extension Pack
• Language Support for Java™ by Red Hat
• Lombok Annotations Support for VS Code
• Checkstyle for Java
• Debugger for Java
• Java Decompiler
• Java Dependency Viewer
• Java Extension Pack
• Java Test Runner
• Jetty for Java
• Maven for Java
• Spring Boot Dashboard
• Spring Boot Extension Pack
• Spring Boot Tools
• Spring Initializr Java Support
• Tomcat for Java

Python

• MagicPython
• Python

Rust

• CodeLLDB
• Rust (rls)
• rust-analyzer
• crates
• Rust Test Explorer

Go

• Go

Dart&Flutter

• Dart
• Flutter

文档&绘图&数据

• Excel Viewer
• Data Preview
• PlantUML
• Markdown Extension Pack
• Markdown All in One
• Markdown Emoji
• Markdown PDF
• Markdown Preview Enhanced
• Markdown TOC
• Markdown+Math
• markdownlint

Scala

• Scala Syntax (official)
• Dotty Language Server
• Scala (Metals)
• Scala (sbt)
• Scala Language Server

Shell

• Shebang Snippets
• shell-format
• shellcheck
• shellman

其他语言配置文件支持

• Better TOML
• FreeMarker
• SSH Tooling
• systemd-unit-file
• Thrift
• vscode-proto3
• XML
• XML Tools
• YAML
• DotENV
• LaTeX Workshop
• SVG Viewer
• Output Colorizer

相关平台

• 爱企查 —— 免费 企业信息 查询（天眼查和企查查需要收费）
• 全国12315平台

投诉内容

2019年8月2日，在位于 合川路2850号的 【鑫尚国际】 充值 1000 元五折会员卡，并以手机号作为凭证，此后可以30元进行理发，并且未提供实体卡。2020年4月左右，合川路2850号 停业装修 更名为 【维纳斯】，并承诺仍可以继续使用旧卡，理发涨价到34元，此后每次前往，都以各种理由让你续费（威胁说不续费就不能使用）。2020年8月24日，理发店称必须提供实体卡，但是凭上次小票可以作为凭据，此次仍使用了会员卡。2020年9月28日，理发店称，以持卡消费为由，拒绝我凭手机号使用会员卡，于是付款原价 68元（收款码显示为【上海威天美容美发有限公司】）。既然无法使用，期望可以退款卡中余额621元，并退换本次理发多收的34元。经查询公司实体为【上海威天美容美发有限公司】，法定代表人在2020-03-26日发生变更。类似事件：微博卡里余额2.5万继续用得再充2.5万。法条：消协法五十三条

结果

几个工作日内，工商管理局介入协商，理发店最终同意继续使用该卡。

总结

• 在保证自己在法律上有法可依的情况下，遇到类似事件可进行投诉
• 协商过程尽量提出自己的诉求，这次处理个人不是很满意。我主张进行退款，但是工商管理局给的方案是可继续使用而已，没有完全达成目标，还要继续到该店中进行理发，继续忍受理发店人员的语言轰炸

VSCode Go 扩展版本 0.29.0

阅读本章节，可以了解到如何使用 VSCode 开发 Go 语言项目，并可以获取到基本不输于 Goland 的体验。

特性速览

• 智能感知（自动完成、Hover、函数签名）
• 代码导航（调转定义、查找引用、查找实现、调用层次）
• 代码编辑（代码片段、包导入、格式化）
• 重构和代码生成
• 构建、测试和运行调试
• 问题诊断
• 其他（Go Playground）

关于这些特性，介绍，参见 VSCode 官方文档

快速开始

参考：官方文档

• 安装 Go，参见 Go 官方文档
• 安装 VSCode，并在 VSCode 中，安装 Go 扩展
• 使用 VSCode 打开包含一个 Go 项目目录 （包含 go.mod 的目录），按照提示安装依赖工具即可
• Enjoy it!

使用指南

状态和环境管理

参考：官方文档

安装完 Go 扩展，并打开一个 Go 项目后。可以通过左下角状态栏，观察到当前系统的 Go 环境和状态。例如 Go 1.17.1 ⚡，表示当前系统 Go 版本，⚡ 代表已经使用 gopls 提供能力。

点击状态栏按钮，可以做如下事情

• 打印当前系统的详细状态信息（go env），以及安装的命令行工具。
• Choose Go Environment，可以快速选择或者安装其他版本的 Go。
• 显示 gopls 的日志

依赖的命令行工具

参考：官方文档

Go 扩展 依赖一些社区开发的命令行工具。通过 >Go: Install/Update Tools 命令进行安装。

使用 gopls 模式的依赖工具如下表所示（默认）

使用 legacy 模式的依赖工具如下表所示（通过 "go.useLanguageServer": false 启用该模式），不建议使用，具体参见：官方文档

如果想把命令行工具安装到指定位置，可以通过 "go.toolsGopath" 配置项指定。更多关于安装位置，参见官方文档

特性详解

参考：官方文档

智能感知

• 建议列表 editor.action.triggerSuggest，快捷键 cmd + i
• 显示悬浮文档 editor.action.showHover，快捷键 cmd+k cmd+i
• 显示参数和参数位置提示 editor.action.triggerParameterHints，快捷键 cmd+shift+space

代码导航

代码编辑器鼠标右击，打开上下文菜单，可以调转定义、查找引用、查找实现、调用层次

• 调转定义 editor.action.revealDefinition ，快捷键 F12

• 查找引用 editor.action.goToReferences，快捷键 shift+F12

• 查找实现 editor.action.goToImplementation，快捷键 cmd+F12，光标在接口上

• 查找工作空间所有符号

• 调用层次 references-view.showCallHierarchy，快捷键 shift+option+H，命令名 >Calls: Show Call Hierarchy

• Explorer （资源管理器）的 Outline （大纲），可以看到当前编辑器打开文件的符号列表

• >Go: Toggle Test File 命令可以快速切换到当前文件的测试文件

代码编辑

动态代码片段

在一个表达式后输入 .，有两种常用操作

• .var!，将该函数赋值给一个变量 x, x := 表达式
• .print!，将生成fmt.Printf("c: %v\n", 表达式)

静态代码片段

完整列表，参见：配置文件

包导入

• 默认保存的时候会自动导入 go.mod 中声明的包。如果，包没有在 go.md 中声明，将光标放到 import 语句位置，按 cmd+. 选择 go get xxx，即可快速导入。
• 通过 Go: Add Import 命令，可以查找所有 GOPATH 和 Go module cache 中的包，并快速添加到 import 块中。

格式化

代码保存是将默认执行格式化。

重构和代码生成

符号重命名

Go 可以重命名工作空间的所有符号，将光标位于需要重命名的符号处，通过 Rename 命令，快捷键为 F2 触发。

提取表达式

选中一段代码，按 cmd+. 可能触发两种重构行为

• 提取表达式到变量
• 提取代码块到函数

添加和删除结构体 tags

光标聚焦于结构体定义位置，执行命令 Go: Add Tags to Struct Fields 、>Go: Remove Tags From Struct Fields 可以给结构体批量添加或删除 tags。

tags 的格式，通过如下配置项配置，配置项的含义，参见 gomodifytags

{
    "go.addTags": {
        "tags": "json",
        "options": "json=omitempty",
        "promptForTags": false,
        "transform": "snakecase",
        "template": ""
    }
}

为结构体实现方法

通过 >Go: Generate Interface Stubs 命令，并输入 $接收者名 $结构体类型 $要实现的接口，在光标处为该结构体生成相关接口的方法

生成测试

通过 >Go: Generate Unit Tests for 可以快速生成单元测试文件和表格驱动的单元测试函数。该能力由 gotests 提供

填充结构体类型实例化字段

光标位于结构体类型实例化语句内，通过 cmd+. 选择 fill Xxx，或者 >Go: Fill struct 命令，即可快速填充结构体字段

构建、测试和运行调试

调试或运行项目

想调试、运行项目（main 函数），需要创建 VSCode 调试配置文件 .vscode/launch.json 文件并添加 Golang 配置。流程如下：

• cmd + p 输入 debug，选择添加配置，选择 Go: Launch Package 回车将创建并打开 .vscode/launch.json 文件
• 启动调试，有如下几种方式
  • F5 或者 >Debug: start debugging 以上次选中的调试配置启动调试
  • cmd + p 输入 debug 并选择调试配置，并启动调试
  • 打开调试侧边栏，绿色三角号
  • 菜单 > Run > Start debugging
• 运行（不调试），有如下几种方式
  • ctrl+F5 或者 >debug: start without debugging
  • 菜单 > Run > start without debugging

关于调试运行配置，参见下文

测试浏览器

测试、基准和覆盖度

• 测试启动可以通过如下方式运行或者调试
  • 点击测试函数上方的 Code Lens
  • 测试侧边栏，可以看到当前工作空间所有测试文件和函数鼠标点击
  • 通过命令如下命令启动
    • >Go: Test Function At Cursor
    • >Go: Test File, Go: Test Package
    • >Go: Test All Packages in Workspace
• 测试覆盖度
  • 测试覆盖度运行后，编辑器会通过绿色背景色来表示哪些代码被覆盖了，红色背景色表示哪些代码没有被覆盖
  • 通过如下命令触发
    • Go: Apply Cover Profile
    • Go: Toggle Test Coverage in Current Package
  • 一些配置如下
    • "go.coverOnSave" 可以在保存文件时自动执行覆盖度计算（注意性能）
    • "go.coverOnSingleTest" 可以在执行单测试函数时自动执行覆盖度计算
    • "go.coverOnSingleTestFile" 可以在执行某个测试文件时自动执行覆盖度计算
    • "go.coverShowCounts" 可以在覆盖度计算后再函数和条件语句后面显示命中次数
• >Go: Toggle Test File 命令可以快速切换到当前文件的测试文件

问题诊断

问题诊断主要有3种

• 第一种为 编译级别错误。通过 "go.buildOnSave" 配置项配置保存时编译的范围，来控制检查的代码文件
• 第二种为 Vet 错误。通过 "go.vetOnSave" 配置项配置保存时执行 go vet 的范围，来控制检查的代码文件
• 第三种为 lint 工具提供的检查，可以通过 "go.lintTool" 配置项选择使用的 lint 工具，如果使用的是 staticcheck，可以通过 "gopls": { "ui.diagnostic.staticcheck": true } 来让其运行在 gopls 中

其他特性

Go Playground

>Go: Run On Go Playground 命令可以把当前文件快速上传到 https://play.studygolang.com/ （大陆地区无法使用）

断点调试

本部分介绍的是基于 dlv-dap 模式调试程序，参考：官方文档

通过 .vscode/launch.json 配置文件的 configurations 字段，来配置调试器

简单的例子：当前打开的工作空间是一个 main 包

{
    "name": "Launch Package",
    "type": "go",
    "request": "launch",
    "mode": "auto",
    "program": "${workspaceFolder}"
}

配置字段

• name 配置名称，可以随意设置
• type 调试器类型，必须是调试 go 程序，必须是 go
• request 可选项为 launch 或 attach，launch 为调试器会启动一个新的进程，attach 为调试器会连接到已经存在的进程或远端端口
• mode 调试模式
  • 当 request 为 launch 可选项为：
    • debug 构建并 debug 一个 main 包
    • test 构建并 debug 一个 测试文件
    • exec 调试编译好的的二进制文件。二进制文件需要使用 -gcflags=all="-N -l" 标志来构建，以避免剥离调试信息
    • auto 根据打开的文件自动选择 debug 或 test 模式
    • core 调试核心转储文件
    • replay 没找到相关文档
  • 当 request 为 attach 可选项为：
    • local 连接到本机进程，对应执行 dlv attach ... 命令，需要填写 processId 字段
    • remote 连接到远程进程，需要填写 host 和 port 字段
• request 为 launch 时配置属性
  • args 命令行参数，默认为 []
  • backend delve 使用的后端，传递到 dlv 的 --backend 标志，可选值为 "default", "native", "lldb", "rr"
  • buildFlags 构建时使用的标志，传递到 dlv 的 --build-flags 标志，默认为 []
  • coreFilePath 核心转储文件路径，传递到 dlv 仅当 mode 为 core 时有效
  • cwd 默认为当前包所在路径
  • env 传递给程序的环境变量
  • envFile 包含环境变量定义的文件的绝对路径。可以通过提供一组绝对路径来指定多个文件，默认为 ${workspaceFolder}/.env
  • output 被调试者的二进制文件的输出路径。默认为 "debug"
• debugAdapter 调试适配器模式 "legacy", "dlv-dap" （默认），关于两种模式说明参见下文
• dlvFlags dlv 的额外标志。有关受支持的完整列表，请参阅 dlv help。 --log-output、--log、--log-dest、--api-version、--output、--backend 等标志在调试配置中已经有相应的属性，并且 --listen和 和 -headless 在内部使用。如果它们在 dlvFlags 中指定，它们可能会被忽略或导致错误。
• hideSystemGoroutines 是否在调用栈视图中隐层系统 goroutine，默认为 false
• host
  • 当 debugAdapter 为 "dlv-dap" (which does not yet support remote-attach)，表示 host 所在机器上，必须有 "dlv dap --listen=:" 监听的端口
  • 当 debugAdapter 为 "legacy"，仅在 request 为 attach 且 mode 为 remote 时有效，表示该 host 所在机器上，必须有 dlv ... --headless --listen=: 监听的端口
• port 远端端口， 和 host 类似
• logDest dlv 的 --log-dest 标志。有关详细信息，请参阅 dlv log。不允许使用数字参数。仅在 debugAdapter 为 "dlv-dap" 且系统为 Linux 和 Mac OS 上受支持。
• logOutput 映射到 dlv 的 --log-output 标志。请参阅 dlv log，允许值为 "debugger", "gdbwire", "lldbout", "debuglineerr", "rpc", "dap"。(默认为 "debugger")
• remotePath 废弃
• showGlobalVariables 变量视图是否展示全局变量
• showLog 映射到 dlv 的 --log 选项（默认为 false）
• showRegisters 是否在变量视图显示寄存器变量（默认为 false）
• stackTraceDepth dlv 收集的最大栈深度（默认为 50）
• stopOnEntry 启动后自动暂停程序（默认为 false）
• substitutePath 从本地路径（编辑器）到远程路径（调试器）的映射数组。在使用符号链接的文件系统中工作、运行远程调试或调试外部编译的可执行文件时，此设置很有用。调试适配器将在所有调用中用远程路径替换本地路径。
  • "from": 将路径传递给调试器时要替换的绝对本地路径（默认为 ""）
  • "to"：将路径传回客户端时要替换的绝对远程路径（默认为 ""）
• processId 仅 request 为 attach 且 mode 为 local 可用，可以填写如下内容
  • 非零数字，直接attach到对应 pid 的进程
  • 字符串，则认为是进程名，需要先找到对应进程，然后再 attach，如果存在多个则弹出选择框
  • 0，列出所有进程，然后再选择一个进程（默认）

• trace 调试控制台和 "Go Debug" 输出面变中，显示的各种级别的日志记录。当 debugAdapter 为 "legacy"，如果将日志设置为 error 以外的值，日志也将写入文件。可选值 "verbose", "trace", "log", "info", "warn", "error"（默认值 "error"）
• traceDirPath Directory in which the record trace is located or to be created for a new output trace. For use on ‘replay’ mode only (Default: “”)

调试行为

• 继续/暂停 F5
• 单步跳过 F10
• 单步进入 F11
• 单步跳出 ⇧F11
• 重启 ⇧⌘F5
• 停止 (当 request 为 launch 时) ⇧F5
• 断开连接 (当 request 为 attach 时) ⇧F5
• Terminate (当 request 为 attach 时) ⌥⇧F5

关于停止或者断开 debug 连接的行为为（大概的意思可能是：local 断开后，进程不会停止；remote 取决于远端 dlv --headless 的配置，原文如下）

• Disconnect: disconnect the client and
  • local: leave the target process running (dlv terminates).
  • remote: let dlv decide if it can continue running (--accept-multiclient mode only); if so, the target will stay in halted or running state it was in at disconnect.
    • dlv debug/test/exec: terminate the target process if dlv terminates.
    • dlv attach: leave the target process running even if dlv terminates.
• Stop: stop the attached server and the target process.

断点

• 普通断点，点击编辑器左侧边框，在指定行添加断点，或者在光标所在位置按 F9

• 条件断点，右击编辑器左侧边框，选择条件断点
  • 表达式类型，输入一个结果为 bool 的表达式
  • 命中次数类型
    • 支持一个确定的整数
    • 支持比较运算符 (>, >=, <, <=, ==, !=) 加一个整数
    • 支持 % n 表示每命中 n 次断点一次

• 函数断点，在测试侧边栏中，最下方断点视图，点击加号，输入当前打开文件的函数名

• Logpoint，暂不支持

数据检查

观察方式

• 通过将鼠标 hover 在要观察的变量上观察其变量值。

• 通过调试侧边栏，变量视图，观察当前调用函数内的局部变量值。注意 shadowed 的变量将通过 (变量名) 方式展示

• 通过调试侧边栏，监视视图，观察指定的局部变量和全局变量值。
• 通过 DEBUG CONSOLE，输入命令，详见 Delve expression，调用函数的语法为 call <function_call_expression>

默认情况下，变量视图不会展示全局变量，如果需要展示，需在调试配置里面添加 showGlobalVariables，或者配置 go.delveConfig

在变量和监视视图，变量右击可以做如下操作

• Set Value：只能更改简单的字符串、数字、指针值
• Copy Value：将值复制到剪贴板
• Copy as Expression：当您需要从 DEBUG CONSOLE 面板中的 REPL 进行查询时，这很有用

• Add to Watch：这将自动将表达式添加到 WATCH 部分

调用栈

可以在 在测试侧边栏，调用栈视图，观察所有 goroutines。并可以做如下操作

1. Goroutine 栈的函数名和内部 ID
2. 当前的 goroutine 将使用 * 标识. 如果多个 goroutines 同时暂停（例如命中断点），Delve 将随机选择一个。也可能没有当前的 goroutine（例如，死锁、暂停或未运行 goroutine 的系统线程命中的内部断点）。
3. 单击 goroutine 调用堆栈，则会选择该 goroutine。效果是可以看到当前运行到的位置并检查变量
4. 可以选择所选 goroutine 的帧（某个函数调用层次）。 VARIABLE 和 WATCH 部分将相应更新，编辑器中的光标将移动到源代码中的相应位置。
5. 不可以检查的堆栈帧将变灰或折叠
6. 为调度的 goroutine 显示线程 ID
7. 暂停理由。 goroutine 被暂停的原因可能有多种，但目前只给出了一个原因。
8. 函数帧的的文件名和行号。
9. 您可以使用选定的 goroutine 触发调试操作。注意：当前不支持仅恢复或停止单个 goroutine（Go Issue 25578、31132），因此该操作将导致所有 goroutine 被激活或暂停。
10. 帧的函数名称。

当程序由于异常、panic 或错误访问错误而停止时，CALL STACK 会显示停止原因，并且编辑器会用更多详细信息突出显示源位置。

legacy 和 dlv-dap 模式

扩展版本 0.29.0

VSCode Go 的调试协议发展了两个版本：legacy 和 dlv-dap。目前默认已经使用 dlv-dap 了。两者的原理如下所示

dlv-dap 模式的原理为：

VSCode DAP Client ---(dap协议)---> dlv-dap server ------> debugee

legacy 模式的原理为：

VSCode DAP Client ---(dap协议)---> Golang 扩展 JS 实现的 Legacy DAP Server ---(dlv私有协议)---> dlv server ------> debugee

官方对比如下图所示

可以看出 legacy 有一个中转层，而 dlv-dap 则更加直接。

但是注意，某些场景下目前仍需要使用 legacy 模式，如：Go 版本小于等于 Go 1.14

legacy 模式不再建议使用，如需了解，参见：官方文档

dlv 全局配置

{
    "go.delveConfig": {
        "debugAdapter": "dlv-dap", // 默认为 dlv-dap, 可选值为 dlv-dap, legacy
        // 仅列出两种模式均可用的配置项
        "dlvFlags": [], // dlv help，参见上文调试配置
        "hideSystemGoroutines": false, // 默认为 false，参见上文调试配置
        "logOutput": "debugger", // 默认为 debugger，参见上文调试配置
        "showGlobalVariables": false, // 默认为 false，参见上文调试配置
        "showLog": false, // 默认为 false，参见上文调试配置
        "showRegisters": false, // 默认为 false，参见上文调试配置
        "substitutePath": [], // 参见上文调试配置
    }
}
// 仅 legacy 模式可用配置
{
    "go.delveConfig": {
        "debugAdapter": "legacy",
        "apiVersion": 2, // 可选值为 1, 2 (默认为 2)
        "dlvLoadConfig": {
            "followPointers": true,
            "maxVariableRecurse": 1,
            "maxStringLen": 64,
            "maxArrayValues": 64,
            "maxStructFields": -1
        }
    }
}

当 debugAdapter 为 dlv-dap 同时配置了 dlvLoadConfig，将会弹出如下提示。

远程 Debug

方式一：远程运行的是 headless dlv

远端执行如下命令

# 使用 -gcflags='all=-N -l' 编译出可执行文件
dlv debug /path/to/program --headless --listen=:12345

VSCode 调试配置如下

{
    "name": "Connect to external session",
    "type": "go",
    "debugAdapter": "dlv-dap",
    "request": "attach",
    "mode": "remote",
    "port": 12345, // 远端端口
    "host": "xxx.xxx.xxx.xxx", // 远端 ip 或者 host
    "substitutePath": [
      { "from": "${workspaceFolder}", "to": "/path/to/remote/workspace" },
    //   ...
  ]
}

• 注意：远端如果使用 --accept-multiclient 参数启动，则可以支持断开连接后，远端的 dlv 不会停止

方式二：远程运行的是 dlv-dap

远端执行如下命令

cd /path/to/remote/workspace # 目的是让 dlv-dap 可以自动编译程序
dlv-dap dap --listen=:12345

VSCode 调试配置如下

{
    "name": "Connect and launch",
    "type": "go",
    "debugAdapter": "dlv-dap",
    "request": "launch",
    "port": 12345, // 远端端口
    "host": "xxx.xxx.xxx.xxx", // 远端 ip 或者 host
    "mode": "exec", // 这种模式需要手动前往 使用 -gcflags='all=-N -l' 编译出可执行文件
                    // 还支持 debug、test 模式，此时远端的 dlv-dap 将会先编译程序在启动调试
    "program": "/absolute/path/to/remote/workspace/program/executable",
    "substitutePath": [
        { "from": "${workspaceFolder}", "to": "/path/to/remote/workspace" },
    ]
}

注意：

• Delve DAP 不支持代码同步，因此 mode 为 debug、test 模式，编译的代码是远端的代码
• Delve DAP 1.7.3：Delve DAP 不支持 --accept-multiclient 或 --continue 标志，这意味着在调试会话结束后，dlv-dap 进程将始终退出。1.7.3 之后已经支持

官方报告调试相关问题

参见：官方文档

gopls 配置

参考：官方文档

参见下文：全部配置项 的 gopls 配置

全部命令列表

扩展版本 0.29.0，参考：官方文档

全部配置项

扩展版本 0.29.0，参考：官方文档

除非特殊说明，下文配置项的值为默认值。

{
    "go.buildOnSave": "package", // 保存时自动构建的范围
    "go.buildFlags": [], // 如 ["-ldflags='-s'"] 在 build-on-save 或者运行测试时编译参数。如果 `gopls.build.buildFlags` 没指定，则使用该参数
    "go.buildTags": [], // 支持 -tags '' （条件编译） ，运行测试时，如果 go.testTags 没指定，则使用该参数。如果 `gopls.build.buildFlags` 没指定，则使用该参数
    "go.testTags": null, // 参见 go.buildTags
    "go.disableConcurrentTests": false, // 使用禁用并发测试，如果该配置为 true，则新的测试运行时，旧的测试将被取消
    "go.installDependenciesWhenBuilding": false, // go build 时传递 -i 参数，非 go mod 模式可能才需要配置
    "go.lintOnSave": "package", // 保存时自动 lint 的范围
    "go.lintTool": "staticcheck", // lint 工具
    "go.lintFlags": [], // lint 工具 flag，如 ["-min_confidence=.8"]
    "go.vetOnSave": "package", // 保存时自动 vet 的范围
    "go.vetFlags": [],  // go tool vet 参数，如 ["-all", "-shadow"]
    "go.gopath": null, // 指定 GOPATH，go.inferGopath 为 true 推导出的 GOPATH 优先级高于该配置（如果该配置在 .vscode/settings.json 中配置，仅当 "Go: Toggle Workspace Trust Flag" 为信任时才生效）
    "go.toolsGopath": null, // 扩展依赖的命令行工具编译安装时使用的 GOPATH，如果没有指定，则使用系统 GOPATH（如果该配置在 .vscode/settings.json 中配置，仅当 "Go: Toggle Workspace Trust Flag" 为信任时才生效）
    "go.goroot": null, // 指定 GOROOT（如果该配置在 .vscode/settings.json 中配置，仅当 "Go: Toggle Workspace Trust Flag" 为信任时才生效）
    "go.testOnSave": false, //	是否在保存时对当前包运行 'go test'
    "go.coverOnSave": false, // 是否在保存时对当前包运行 'go test -coverprofile'
    "go.coverOnTestPackage": true, // 在执行 Go: Test Package 是否计算覆盖度
    "go.coverOnSingleTest": false, // 在执行 Go: Test Function at cursor 时是否计算覆盖度
    "go.coverOnSingleTestFile": false, // 在执行 Go: Test Single File 时是否计算覆盖度
    "go.coverMode":	"default", // 覆盖度模式
    "go.coverShowCounts": false , // 运行覆盖度时，是否在编辑器中显示函数和条件的命中次数如 --374--
    "go.coverageOptions": "showBothCoveredAndUncoveredCode", // 覆盖度结果在编辑器中的显示样式
    "go.coverageDecorator": { // 覆盖度结果显示的样式
        "type": "highlight",
        "coveredHighlightColor": "rgba(64,128,128,0.5)",
        "uncoveredHighlightColor": "rgba(128,64,64,0.25)",
        "coveredBorderColor": "rgba(64,128,128,0.5)",
        "uncoveredBorderColor": "rgba(128,64,64,0.25)",
        "coveredGutterStyle": "blockblue",
        "uncoveredGutterStyle": "slashyellow"
    },
    "go.testTimeout": "30s", // 测试超时时间
    "go.testEnvVars": {}, // 测试运行时的环境变量
    "go.testEnvFile": "", // 测试时环境变量的绝对路径
    "go.testFlags": "", // 构建测试时的 flag，参见 go.buildFlags
    "go.testExplorer.enable": true, // 是否启用测试浏览器
    "go.testExplorer.packageDisplayMode": "flat", // Present packages in the test explorer flat or nested.	flat
    "go.testExplorer.alwaysRunBenchmarks": false, // 运行所有测试时，是否也运行基准测试
    "go.testExplorer.concatenateMessages": true, // Concatenate all test log messages for a given location into a single message
    "go.testExplorer.showDynamicSubtestsInEditor": false,	// 动态发现的子测试是否显示到测试浏览器中
    "go.testExplorer.showOutput": true, // 开始测试运行时打开测试输出终端 
    "go.generateTestsFlags": null, // 生成测试的命令行参数，去 https://github.com/cweill/gotests 查看
    "go.toolsEnvVars": {}, // 运行命令行工具时的环境变量
    "go.useLanguageServer": true, // 启用 gopls
    "go.languageServerFlags": [], // gopls 命令行参数 Flags like -rpc.trace and -logfile to be used while running the language server.	
    "go.languageServerExperimentalFeatures": { "diagnostics": true }, // 临时标志去 enable/disable gopls 的 diagnostics 能力.很快要废弃了. 请看 Issue 50: https://github.com/golang/vscode-go/issues/50
    "go.trace.server": "off", // 跟踪 VS Code 和 Go 语言服务器之间的通信。
    "go.logging.level": "error", // 扩展日志登记
    "go.toolsManagement.checkForUpdates": "proxy", // 指定是否提示新版本的 Go 以及扩展依赖的 Go 工具（目前只有 gopls） 
    "go.toolsManagement.autoUpdate": false, // 自动更新扩展依赖的命令行工具，不提示用户 
    "go.useGoProxyToCheckForToolUpdates": true, // 启用后，扩展程序会自动检查 Go 代理是否有可用于 Go 和它所依赖的 Go 工具（目前只有 gopls）的更新，并相应地提示用户
    "go.enableCodeLens": {
        "references": false, // 函数上的引用次数
        "runtest": true // 测试上面的运行/debug
    }, // 配置 CodeLen
    "go.addTags": {
        "tags": "json",
        "options": "json=omitempty",
        "promptForTags": false,
        "transform": "snakecase",
        "template": ""
    }, // 添加标签命令将使用此处配置的标签和选项将标签添加到结构字段。如果 promptForTags 为 true，则将提示用户输入标签和选项。默认添加json标签。 
    "go.removeTags": {
        "tags": "",
        "options": "",
        "promptForTags": false
    }, // 此处配置的标签和选项将被移除标签命令用于移除结构字段的标签。 如果 promptForTags 为 true，则将提示用户输入标签和选项。 默认情况下，所有标签和选项都将被删除。
    "go.playground": {
        "openbrowser": true,
        "share": true,
        "run": true
    }, // 此处配置的标志将传递给命令 `goplay`
    "go.survey.prompt": true, // 是否展示问卷调查
    "go.editorContextMenuCommands": {
        "toggleTestFile": true,
        "addTags": true,
        "removeTags": false,
        "fillStruct": false,
        "testAtCursor": true,
        "testFile": false,
        "testPackage": false,
        "generateTestForFunction": true,
        "generateTestForFile": false,
        "generateTestForPackage": false,
        "addImport": true,
        "testCoverage": true,
        "playground": true,
        "debugTestAtCursor": true,
        "benchmarkAtCursor": false
    }, // 实验性功能：从编辑器的上下文菜单中启用/禁用条目。
    "go.delveConfig": {}, // dlv 配置
    "go.alternateTools": {}, // 为每一个 go 扩展依赖的外部工具提供绝对路径，比如想包装一下你的工具，如 "gopls": "/path/to/gopls"
    "gopls": { // 配置 gopls，默认值为 {}，详见：https://github.com/golang/tools/blob/master/gopls/doc/settings.md
        // 构建
        "build.buildFlags": [], // 构建标志
        "build.env": {}, // 环境变量
        "build.directoryFilters": ["-node_modules"], // 目录过滤器，配置方法参见： https://github.com/golang/tools/blob/master/gopls/doc/settings.md#directoryfilters-string
        "build.templateExtensions": ["tmpl","gotmpl"], // go template 扩展名
        "build.memoryMode": "Normal", // <实验性> DegradeClosed ，在 DegradeClosed 模式下，gopls 将收集关于没有打开文件的包的较少信息。因此，诸如 Find References 和 Rename 之类的功能将错过此类包中的结果。
        "build.expandWorkspaceToModule": true, //  <实验性> expandWorkspaceToModule 指示 gopls 调整工作区的范围以找到最佳的可用模块根。 gopls 首先在工作区文件夹的任何父目录中查找 go.mod 文件，如果存在，则将范围扩展到该目录。如果找不到可行的父目录，gopls 将检查是否只有一个包含 go.mod 文件的子目录，如果存在，则将范围缩小到该目录。
        "build.experimentalWorkspaceModule": false, // <实验性>  选择用户加入对多模块工作区的实验支持。
        "build.experimentalPackageCacheKey": false, // <实验性> 控制是否对包类型信息使用更粗略的缓存键以增加缓存命中。此设置从缓存键中删除用户的环境、构建标志和工作目录，这应该是一个安全的更改，因为类型检查传递的所有相关输入都已散列到键中。这是由实验暂时保护的，因为缓存行为是微妙的，难以全面测试。
        "build.allowModfileModifications": false, // <实验性> 禁用 -mod=readonly，允许从范围外模块导入。此选项最终将被删除。
        "build.allowImplicitNetworkAccess": false, // <实验性> 禁用 GOPROXY=off，允许隐式模块下载而不需要用户操作。此选项最终将被删除。
        "build.experimentalUseInvalidMetadata": false, // <实验性> 如果 go 命令由于某种原因（例如无效的 go.mod 文件）无法加载包，则 ExperimentUseInvalidMetadata 使 gopls 能够回退到过时的包元数据以提供编辑器功能。这最终将成为默认行为，并且此设置将被删除。

        // 格式化
        "formatting.local": "", // local 相当于 goimports -local 标志，它将以该字符串开头的导入放在第三方包之后。它应该是导入应该单独分组的导入路径的前缀。
        "formatting.gofumpt": false, // gofumpt 指示我们是否应该运行 gofumpt 格式化。gofumpt 是比 go fmt 更严格的规范，https://github.com/mvdan/gofumpt

        // UI
        "ui.codelenses": { // 参见 https://github.com/golang/tools/blob/master/gopls/doc/settings.md#code-lenses
            "gc_details": false,
            "generate": true,
            "regenerate_cgo": true,
            "tidy": true,
            "upgrade_dependency": true,
            "vendor": true
        },
        "ui.semanticTokens": false, // 是否 gopls 把语义化令牌发到 UI 上，开启后，有更好的高亮效果
        "ui.completion.usePlaceholders": false, // 函数调用的自动完成是否填充参数列表
        "ui.completion.completionBudget": "100ms", // 此设置仅用于调试目的。完成请求的耗时预算。大多数请求在几毫秒内完成，但在某些情况下，深度完成可能需要更长的时间。当我们用完预算时，我们会动态缩小搜索范围，以确保及时返回结果。零意味着无限。
        "ui.completion.matcher": "Fuzzy", // 匹配算法，可以是 Fuzzy、CaseSensitive、CaseInsensitive
        "ui.completion.experimentalPostfixCompletions": true, // <实验性> 启用后缀补全，例如 "someSlice.sort!"
        "ui.diagnostic.analyses": {
            // 再次记录没有默认开启的分析器
            "fieldalignment": true, // 结构体排序检查，那种排列内存占用更小，但是没有提供自动修复的功能，不建议开启
            "nilness": true, // 对于 nil 的一些检查
            "shadow": true, // 检查变量覆盖
            "unusedparams": true, // 未使用的参数
            "unusedwrite": true, // 未使用的写入
        }, // 分析器配置，参见 https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md
        "ui.diagnostic.staticcheck": false, // 启用 staticcheck 分析器，让 lint 在 gopls 中执行
        "ui.diagnostic.annotations": {"bounds":true,"escape":true,"inline":true,"nil":true}, // 注释指定应由 gc_details 命令报告的各种优化诊断。
        "ui.diagnostic.diagnosticsDelay": "250ms", // 参见 https://github.com/golang/tools/blob/master/gopls/doc/settings.md#diagnosticsdelay-timeduration
        "ui.diagnostic.experimentalWatchedFileDelay": "0s", // <实验性> 参见 https://github.com/golang/tools/blob/master/gopls/doc/settings.md#experimentalwatchedfiledelay-timeduration
        "ui.documentation.hoverKind": "FullDocumentation",  // hover 种类
        "ui.documentation.linkTarget": "pkg.go.dev", // link 目标
        "ui.documentation.linksInHover": true, // 在 hover 中显示链接
        "ui.navigation.importShortcut": "Both", // 导入块执行调转到定义的方式，可以是 Both、Definition、Link
        "ui.navigation.symbolMatcher": "Fuzzy", // 设置查找工作区符号时使用的算法，可以是 Fuzzy、FastFuzzy、CaseSensitive、CaseInsensitive
        "ui.navigation.symbolStyle": "Dynamic", // 控制符号唯一表示非风格，可以是 Dynamic、Full、Package
        "verboseOutput": false, // 输出 gopls 的详细信息
    },
}
// 非 gopls 模式才生效的配置
{
    "go.formatTool": "default", //  格式化工具
    "go.formatFlags": [], // Flags to pass to format tool (e.g. ["-s"])
    "go.inferGopath": false, // 从工作空间推断 gopath，优先级高于 go.gopath（如果该配置在 .vscode/settings.json 中配置，仅当 "Go: Toggle Workspace Trust Flag" 为信任时才生效）
    "go.gocodeFlags": null, //	gocode 命令行参数 如-builtin,-ignore-case,-unimported-packages
    "go.gocodeAutoBuild": false, //	Enable gocode's autobuild feature
    "go.gocodePackageLookupMode": "go", // Used to determine the Go package lookup rules for completions by gocode. Latest versions of the Go extension uses mdempsky/gocode by default.
    "go.useCodeSnippetsOnFunctionSuggest": false, // Complete functions with their parameter signature, including the variable type.
    "go.useCodeSnippetsOnFunctionSuggestWithoutType": false, // 完成函数的建议列表时，填充函数参数（不包括类型） 如果是 gopls，使用 `gopls.usePlaceholders` 可进行配置。
    "go.autocompleteUnimportedPackages": false, // 在自动完成建议中包含未导入的包 
    "go.docsTool": "godoc", //	选择 'godoc' or 'gogetdoc' 获取文档
    "go.gotoSymbol.includeImports": false, // If false, the import statements will be excluded while using the Go to Symbol in File feature.
    "go.gotoSymbol.includeGoroot": false, // If false, the standard library located at $GOROOT will be excluded while using the Go to Symbol in File feature.
    "go.liveErrors": {
        "enabled": false,
        "delay": 500
    }, // Use gotype on the file currently being edited and report any semantic or syntactic errors found after configured delay.
    "go.gotoSymbol.ignoreFolders": [], // Folder names (not paths) to ignore while using Go to Symbol in Workspace feature.
}

场景

Go 扩展最佳配置

{
    "go.disableConcurrentTests": true, // 禁用并发测试
    "go.testFlags": [
        "-v" // 测试打印标准输出
    ],
    "go.vetFlags": [
        "-all" // vet 执行所有规则
    ],
    "go.testTimeout": "30s", // 测试超时时间
    "go.testExplorer.showDynamicSubtestsInEditor": true, // 动态发现的子测试是否显示到测试浏览器中
    "go.toolsManagement.autoUpdate": true, // 自动更新扩展依赖的命令行工具，不提示用户 
    "go.enableCodeLens": { // 显示的 lens
        "references": true,
        "runtest": true
    },
    "go.addTags": { // 配置 add Tags 命令
        "tags": "json,yaml",
        "options": "json=omitempty",
        "promptForTags": true, // 询问添加的 tag
        "transform": "snakecase",
        "template": ""
    },
    "go.removeTags": { // 配置 remove Tags 命令
        "tags": "",
        "options": "",
        "promptForTags": true // 询问删除的 tag
    },
    // "go.delveConfig": { // dlv 配置，如果特殊场景需要看比较长的字符串时，可以打开该注释，启用该配置
    //     "debugAdapter": "legacy",
    //     "dlvLoadConfig": {
    //         "followPointers": true,
    //         "maxVariableRecurse": 1,
    //         "maxStringLen": 1000000,
    //         "maxArrayValues": 64,
    //         "maxStructFields": -1
    //     }
    // },
    "gopls": {
        "build.experimentalWorkspaceModule": true, // <实验性> 工作空间多模块支持（MonoRepo）
        "build.directoryFilters": ["-node_modules", "-output"], // 构建排除的目录，合理配置可以节省资源
        "formatting.gofumpt": true, // 使用 gofumpt 格式化代码
        "ui.semanticTokens": true,  // 是否 gopls 把语义化令牌发到 UI 上，开启后，有更好的高亮效果
        "ui.completion.usePlaceholders": true,  // 函数调用的自动完成是否填充参数列表
        "ui.diagnostic.analyses": { // 开启默认没有开启的且误报较少的分析器，参见 https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md
            "nilness": true,
            "shadow": true,
            "unusedparams": true,
            "unusedwrite": true,
        },
    },
}

大型项目资源占用优化

参考如下，酌情进行配置，这些配置可能影响稳定性以及功能

{
    "gopls": {
        "build.directoryFilters": ["-node_modules", "-output"], // 将工作空间不是 Go 代码的目录排除出去，配置方法参见： https://github.com/golang/tools/blob/master/gopls/doc/settings.md#directoryfilters-string
        "build.experimentalPackageCacheKey": true, // <实验性> 控制是否对包类型信息使用更粗略的缓存键以增加缓存命中。此设置从缓存键中删除用户的环境、构建标志和工作目录，这应该是一个安全的更改，因为类型检查传递的所有相关输入都已散列到键中。这是由实验暂时保护的，因为缓存行为是微妙的，难以全面测试。

        // 下方配置功能有损
        "build.memoryMode": "DegradeClosed", // <实验性> DegradeClosed ，在 DegradeClosed 模式下，gopls 将收集关于没有打开文件的包的较少信息。因此，诸如 Find References 和 Rename 之类的功能将错过此类包中的结果。
    }
}

关于调试的一些场景和问题

VSCode 打开符号链接上的项目如何调试

如果一个项目，真实路径为 /path/to/actual/helloWorld，同时可以通过一个符号链接访问 /link/to/helloWorld，此时调试配置如下

{
    "name": "Launch with symlinks",
    "type": "go",
    "request": "launch",
    "mode": "debug",
    "program": "/path/to/actual/helloWorld",
    "substitutePath": [
		{
			"from": "/link/to/helloWorld",
			"to": "/path/to/actual/helloWorld",
		},
	],
}

调试时字符串被截断

目前，默认启用了 dlv-dap 模式，因此无法配置 dlv 的字符串长度。这种情况下

• 通过变量视图，直接查看，最多只能看到 512 个字符
• 通过如下方式可以看到 4096 个字符
  • 右击 Copy Value
  • 右击 Copy as Expression，并在 DEBUG CONSOLE 输入
  • 鼠标 Hover 在变量上

如果是更长的字符串，在 dlv-dap 模式下，只能通过 fmt.Println 打印出来查看。

另外不推荐的方法是，切换回 legacy 模式。配置 maxStringLen 属性。

{
    "go.delveConfig": {
        "debugAdapter": "legacy",
        "dlvLoadConfig": {
            "followPointers": true,
            "maxVariableRecurse": 1,
            "maxStringLen": 1000000,
            "maxArrayValues": 64,
            "maxStructFields": -1
        }
    }
}

debug 过程中添加断点后，会暂停一次

已知问题，官方正在处理，可以关注相关 issue

调试编译十分复杂的项目

在编译配置文件添加 debug 模式的构建，添加 -gcflags='all=-N -l' 选项。

配置任务和调试

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch external builded binary",
            "type": "go",
            "request": "launch",
            "mode": "exec",
            "preLaunchTask": "make debug",
            "program": "${workspaceRoot}/path/to/debug-binary",
        }
    ]
}
// .vscode/tasks.json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "make debug",
            "type": "shell",
            "command": "make debug"
        }
    ]
}

如何调试 go 1.14 及之前版本的项目

最新版的 dlv 已经放弃了对 go 1.14 以及之前版本的支持。因此需要安装旧版 dlv，步骤如下所示

• 执行 >Go: Locate Configured Go Tools 命令，确认 dlv 安装位置
• 执行 GOBIN=上面输出的dlv所在目录 GO111MODULE=on go get github.com/go-delve/delve/cmd/dlv@v1.4.1，安装旧版本 dlv

• 确保关闭自动更新并启用 legacy 模式

  {
  "go.toolsManagement.autoUpdate": false,
  "go.delveConfig": {
      "debugAdapter": "legacy",
  }
  }

如何调试 core dump 文件

core dump 是 *nix 类操作系统提供的进程 crash 时刻的进程状态快照。在该文件中，包含进程 crash 时刻的所有堆栈和寄存器信息。利用调试器，可以查看 crash 时刻的各个线程的栈帧，变量。（以下仅在 Linux 测试通过）

假设，编写一个 go 程序，该程序会 sleep 1 小时。在 sleep 的时候通过 ctrl + \ 发送一个 SIGQUIT 信号，制造一个 go 的 coredump 文件。在实验之前确保确保操作系统不限制 core dump 大小：执行 ulimit -a，观察 -c 一行是否为 unlimited。如果不是执行 ulimit -c unlimited （恢复方式为 ulimit -c 原始值）

package main

import (
	"fmt"
	"time"
)

func main() {
	a := 1
	fmt.Println(a)

	// ctrl + \
	time.Sleep(1 * time.Hour)

	b := 2

	fmt.Println(b)
}

编译成带有符号信息的可执行文件

go build -gcflags='all=-N -l' -o main ./

执行（注意环境变量），键盘输入 ctrl + \

GOTRACEBACK=crash ./main

执行 cat /proc/sys/kernel/core_pattern 获取 core dump 路径。

配置 VSCode 调试器 .vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch core dump",
            "type": "go",
            "request": "launch",
            "mode": "core",
            "coreFilePath": "上一步获取到 core dump 文件路径",
            "program": "${workspaceFolder}/main"
        }
    ]
}

按 F5 即可启动调试，此时观察下，调试视图的调用栈视图，即可观察各个栈帧的变量情况。

一键同时调试多个进程

假设某个项目是同时包含客户端和服务端。调试时，希望一键启动客户端和服务端。配置如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Server",
      // ...
    },
    {
      "name": "Client",
      // ...
    }
  ],
  "compounds": [
    {
      "name": "Server/Client",
      "configurations": ["Server", "Client"],
      "preLaunchTask": "${defaultBuildTask}"
    }
  ]
}

更多参见：https://code.visualstudio.com/docs/editor/debugging#_compound-launch-configurations

VSCode Go 插件版本 v0.31.0 远程调试问题

v0.31.0 后，默认 Remote 调试协议已经替换为 dap，因此需要使用，如果远端仍然使用旧的模式，需要在 launch.json 添加 "debugAdapter":"legacy"：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch: server",
            "type": "go",
            "request": "attach",
            "host": "127.0.0.1",
            "port": 2345,
            "debugAdapter":"legacy",
        }
    ]
}

如何高效进行项目源码阅读

• 参见本文的 代码导航 章节
• 阅读依赖包的源码，通过 >Go: Add Package to Workspace，将依赖包加入到工作空间

系统里装了多个版本的 Go SDK，如何管理

可以尝试 >Go: Choose Go Environment 命令，官方解决办法参见：官方文档

多 module 项目 （Go workspace）

参见：官方文档

形如：Golang Multimodule Monorepos 的项目。

Go 1.17 及之前版本

开启如下配置即可开启该特性（目前处于实验阶段）

{
    "gopls": {
        "experimentalWorkspaceModule": true
    }
}

注意，目前处于实验阶段，已知 issue 为：

• 该 feature 与 go mod vender 存在重复，开启后 go mod vender 的项目会报 Inconsistent vendoring detected. Please re-run "go mod vendor". See https://github.com/golang/go/issues/39164 for more detail on this issue. 错误。

其他信息

• 设计文档
• gopls 配置文档
• gopls/workspace-module milestone

Go 1.18 及更新版本

无需任何配置，在根目录添加 go.work 文件，更多参见：Go 1.18 新特性

如何使用 VSCode Go 扩展开发 Go 标准库

解决方法参见：官方文档

存在多个格式化器时如何配置使用 Go 扩展

解决方法参见：官方文档

非 go mod 项目

GOPATH 迁移到 Go modudle 非常容易，建议花少量时间迁移到 Go modudle 模式。如果仍要使用 GOPATH 开发模式，可以参考：官方文档

跨平台开发，如在 Mac 开发 Linux

添加如下 VSCode 配置，参考： github issue

{
    "gopls": {
        "build.env": {
            "GOOS": "linux",
            "GOARCH": "amd64"
        },
    },
}

VSCode Python 扩展版本 v2021.12.1559732655

阅读本章节，可以了解到如何使用 VSCode 开发 Python 语言项目，其功能主要由如下几款 VSCode Python 扩展：

• Python - MIT 许可证
• Jupyter - MIT 许可证 （仅交互式 Python 涉及部分）
• Pylance - 闭源 Microsoft proprietary license
• Visual Studio IntelliCode - 闭源 许可证

特性速览

VSCode Docs - Language Python

• 环境管理
• 代码编辑（自动完成、快速修复、格式化、重构、代码生成、代码片段）
• 代码浏览（调转定义、查找引用、查找实现、调用层次、类型层次）
• 问题诊断（类型检查、Lint）
• 代码运行和调试
• 测试
• 数据分析（本文暂不涉及，后续有专门文章讲解描述）
• 交互式 Python
• 场景
  • Django 支持
  • Flask 支持
  • VSCode Web 支持

快速开始

VSCode Docs - Python Tutorial

• 安装 Python，参见 Python 官方文档
• 安装 VSCode
• 在 VSCode 中，安装如下几个扩展
  • Python - MIT 许可证
  • Jupyter - MIT 许可证
  • Pylance - 闭源 Microsoft proprietary license
  • Visual Studio IntelliCode - 闭源 许可证
• 使用 VSCode 打开 Python 文件或者 Python 项目
• Enjoy it!

使用指南

环境管理

VSCode Docs - Python Environments

一台设备可以装多个 Python 解析器，这些 Python 解释器会关联一些了 Python 包。因此某个和 Python 解释器和其关联的 Python 包的集合称为一个 Python 环境。更多关于 Python 环境，可以参见另一篇文章：一文彻底理解 Python 环境

VSCode Python 支持管理各种的 Python 环境，可以通过状态栏观察当前工作空间绑定的 Python 环境。

点击上图状态栏，可以快速浏览当前系统所有可用的 Python 环境，如下图所示：

选择一个，即可快速和工作空间关联。通过 "python.defaultInterpreterPath" 可以给所有工作空间配置一个默认的 Python 环境。（该配置支持引用环境变量，语法为 ${env:环境变量名}，例如 "python.defaultInterpreterPath": "${env:PYTHON_INSTALL_LOC}"）

Python 环境列表除了通过状态唤起外，还支持通过 >python: select interpreter 命令唤起，该列表默认按照如下逻辑去查找系统内的 Python 环境：

• 操作系统 PATH 环境变量指向的路径（echo $PATH 查看，查找路径）
• 当前工作空间目录的虚拟环境目录（一般为 .venv）
• python.venvPath 配置指向的路径，该路径可以包含多个虚拟环境目录
• virtualenvwrapper 支持的 ~/.virtualenvs 文件夹中的虚拟环境
• 由 pyenv、Pipenv 和 Poetry 安装的解释器
• 位于 WORKON_HOME 环境变量指向目录中的虚拟环境
• 包含 Python 解释器的 Conda 环境（不显示不包含解释器的 conda 环境）
• direnv 安装的 .direnv 目录

此外

• 还可以手动指定 Python 解释器，此外如果在工作空间目录中发现 pipenv 环境，则不会显示其他的 Python 环境，因此 pipenv 会管理这一切。
• Python 扩展还会加载由 python.envFile 配置指向的环境变量文件。默认值为 ${workspaceFolder}/.env

VSCode 选择一个 Python 环境后，其作用范围如下所示：

• 打开终端，会自动选中的 Python 环境，可用通过 "python.terminal.activateEnvironment": false 配置关闭该特性。
• 智能感知、Lint 等特性都会使用该 Python 环境。
• 断点调试时，默认使用该 Python 环境启动调试器（可以通过调试器的 python 字段覆盖默认配置）

默认情况下 Python 扩展会读取 ${workspaceFolder}/.env 文件中定义的环境变量（可以通过 python.envFile 配置自定义）。该文件语法非常简单：

• 通过 environment_variable=value 定义变量
• 使用 # 注释
• 支持 ${env:EXISTING_VARIABLE} 进行变量替换，不支持嵌套

在该文件中定义的环境变量将影响 Language Server 和调试器的行为（如 PYTHONPATH）

代码编辑

智能感知

编写代码中会自动触发建议列表、参数及其位置提示，鼠标 Hover 到代码出会显示对应位置的符号的文档。

• 建议列表 editor.action.triggerSuggest，手动唤起默认快捷键为 cmd + i。
• 显示参数和参数位置提示 editor.action.triggerParameterHints，手动唤起默认快捷键为 cmd+shift+space。
• 显示悬浮文档 editor.action.showHover，手动唤起默认快捷键为 cmd+k cmd+i。

注意：由于 Python 是弱类型语言，在没有启用类型注解的情况下，智能感知的能力是有限的。

Python 的智能感知能力由如下 Language Server 提供，通过 python.languageServer 进行配置

• Default （默认），当安装了 Pylance 时，将使用 Pylance，否则使用 Jedi。
• Jedi 使用 jedi
• None 关闭智能感知

通过 >Python: show language server output 可以输出，关于 Pylance 和 Jedi 参见下文。

智能感知支持添加自定义 Python 包，通过 python.autoComplete.extraPaths 进行配置，如：

"python.autoComplete.extraPaths": [
    "~/.local/lib/Google/google_appengine",
    "~/.local/lib/Google/google_appengine/lib/flask-0.12" ]

快速修复和重构

• 自动导入（需在当前环境中安装相关包）

• 提取变量、提取函数函数

• 符号重命名和模块重命名

• 导入排序 (>Python Refactor: Sort Imports 命令唤起)，可以通过 "python.sortImports.args": ["-rc", "--atomic"], 配置项进行配置。排序脚本参见 isort

格式化

通过 python.formatting.provider 配置项可以配置 Python 格式化器，默认为 "autopep8"，选项为 "autopep8"、"yapf"或"black"。使用这些格式化器时，需要如下配置

• autopep8，pip install pep8 & pip install --upgrade autopep8，特殊的配置项 python.formatting.autopep8Args，python.formatting.autopep8Path
• black，pip install black，特殊的配置项 python.formatting.blackArgs，python.formatting.blackPath （只支持运行在 Python 3 环境）
• yapf，pip install yapf，特殊的配置项 python.formatting.yapfArgs，python.formatting.yapfPath

下面有一些配置例子

"python.formatting.autopep8Args": ["--max-line-length", "120", "--experimental"],
"python.formatting.yapfArgs": ["--style", "{based_on_style: chromium, indent_width: 20}"],
"python.formatting.blackArgs": ["--line-length", "100"]

代码浏览

代码编辑器鼠标右击，打开上下文菜单，可以调转定义、查找引用、查找实现、调用层次

• 调转定义 editor.action.revealDefinition ，快捷键 F12
• 查找引用 editor.action.goToReferences，快捷键 shift+F12
• 查找实现 editor.action.goToImplementation，快捷键 cmd+F12，光标在接口上
• 查找工作空间所有符号
• 调用层次 references-view.showCallHierarchy，快捷键 shift+option+H，命令名 >Calls: Show Call Hierarchy
• Explorer （资源管理器）的 Outline （大纲），可以看到当前编辑器打开文件的符号列表

问题诊断

默认情况下，针对语法问题，VSCode Python 默认会通过 Language Server 对项目进行语法检查。但在 Python 这种弱类型的编程语言的项目路中，如果想在工程中使用，光靠语法检查是不够的，静态代码检查（如代码风格）是必不可少的。因此 VSCode Python 支持与多种 Python 业界主流的 Lint 工具集成。

• 启用或禁用 Lint
  • 方式 1：通过 >Python: Select Linter 命令启用或者禁用 Lint 工具（默认启用 pylint）
  • 方式 2：通过 "python.linting.<linter>Enabled": true 配置启用或禁用 Lint 工具
• 触发 Lint 运行
  • 检查单文件：保存文件时自动触发
  • 检查整个项目：通过 >Python: Run Linting 命令手动触发
• Lint 输出，在编辑器会以波浪线方式展示，并问题面板可以浏览所有问题

• Lint 相关配置

  • python.linting.enabled 是否启用 Lint，默认 true
  • python.linting.lintOnSave 在保存文件时执行 Lint，默认 true
  • python.linting.maxNumberOfProblems 最大问题数量，默认 100
  • python.linting.ignorePatterns 忽略检查的目录或文件，默认为 [".vscode/*.py", "**/site-packages/**/*.py"]

• 不同 Lint 工具集成有不同的配置，需要安装不同的依赖和配置项，所有支持的 Lint 参见下表

• 命令行参数例子

  "python.linting.pylintArgs": ["--reports", "12", "--disable", "I0011"],
  "python.linting.flake8Args": ["--ignore=E24,W504", "--verbose"]
  "python.linting.pydocstyleArgs": ["--ignore=D400", "--ignore=D4"]

• 不同 Lint 工具配置参见下方链接

  • Pylint
  • pydocstyle
  • pycodestyle (pep8)
  • prospector
  • Flake8
  • mypy
  • pylama
  • bandit

代码运行和调试

交互式运行

• >Python: Run Selection/Line in Python Terminal 通过该命令，可以快速启动一个 Python REPL，并将选中代码发送到 该 REPL 中运行。
• >Python: Start REPL 快速启动一个 Python 解释器。
• >Python: run selection/line in Django shell 针对 Django 项目，可以选择在 Django Shell 中运行。
• 还可以田健 #%% 注释，快速在交互式窗口运行，参见下文：交互式 Python

使用默认配置快速运行或调试

VSCode Python 支持免配置的快速启动调试

• 按 F5 快速调试当前文件，按 Ctrl + F5 快速调试当前文件
• 点击调试视图的【运行和调试】按钮
• 点击编辑器标题栏右上角图标快速运行调试当前 Python 文件
  • 点击三角号运行当前文件
  • 点击右侧展开按钮可以调试当前文件

创建或添加调试配置

打开调试视图

• 在没有调试配置时，点击 create a launch.json file
  • 根据情况选择调试的调试配置模板
  • 将创建并打开 .vscode/launch.json 文件
• 在有调试配置时，按可通过如下方式添加一个新的调试配置

调试 Python 文件默认生成的文件配置的例子

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

状态栏调试信息

当存在调试配置时，可以通过状态栏观察当前选中的调试配置，点击可快速选择并启动调试

调试能力详解

在此仅介绍断点能力

• 普通断点，点击编辑器左侧边框，在指定行添加断点，或者在光标所在位置按 F9
• 条件断点，右击编辑器左侧边框，选择条件断点
  • 表达式类型，输入一个结果为 bool 的表达式
  • 命中次数类型
    • 支持一个确定的整数
    • 支持比较运算符 (>, >=, <, <=, ==, !=) 加一个整数
    • 支持 % n 表示每命中 n 次断点一次
  • Logpoint，命中断点后再调试控制台输出日志
• 函数断点，在测试侧边栏中，最下方断点视图，点击加号，输入当前打开文件的函数名
• 通过代码添加断点
  • import debugpy
  • debugpy.breakpoint()

其他调试 VSCode Debug 视图和通用能力，参见：VSCode Docs - User Guide Debugging

选择一个配置启动调试

• cmd + p 输入 debug，选择添加配置，选择 Go: Launch Package 回车将创建并打开 .vscode/launch.json 文件
• 启动调试，有如下几种方式
  • F5 或者 >Debug: start debugging 以上次选中的调试配置启动调试
  • cmd + p 输入 debug 并选择调试配置，并启动调试
  • 菜单 > Run > Start debugging
  • 打开调试侧边栏，绿色三角号

• 运行（不调试），有如下几种方式
  • ctrl+F5 或者 >debug: start without debugging
  • 菜单 > Run > start without debugging

调试配置详解

本部分描述 .vscode/launch.json Python 调试配置支持的全部字段

• name 调试配置名，可以自定义
• type 调试类型，写死 python
• request 可选值为 launch 或者 attach
• request 为 launch 相关配置，配置 debug 的程序如何启动
  • pragram 启动的 Python 文件的绝对路径，可以使用魔法变量如（${file}、${workspaceFolder}，更多参见：变量手册）
  • module 提供指定要调试的模块名称的功能，类似于在命令行运行时的 -m 参数。有关更多信息，请参阅 Python.org
  • python Python 解释器路径。如果未指定，则此设置默认为为您的工作区选择的解释器，相当于使用 ${command:python.interpreterPath}
  • pythonArgs 传递给 Python 解释器的命令行参数
  • console 启动用户程序的终端
    • integratedTerminal 集成终端，即在 VSCode 终端中启动（可以处理标准输入）（推荐）（默认）
    • internalConsole 调试控制台，即在 VSCode 调试控制台启动（不能向进程里面输入标准输入）
    • externalTerminal 外部终端，不建议（调用操作系统中的终端程序）
  • internalConsoleOptions 控制是否如何打开调试控制台
    • neverOpen 从不打开
    • openOnFirstSessionStart" 仅第一次调试时打来
    • openOnSessionStart 每次调试都打开
  • env 环境变量
  • envFile 环境变量文件
  • args 命令行参数
  • stopOnEntry 当设置为 true 时，在被调试程序的第一行中断调试器。如果省略（默认）或设置为 false，调试器将程序运行到第一个断点。
  • autoReload 允许在调试器执行达到断点后对代码进行更改时自动重新加载调试器。要启用此功能，请设置 {"enable": true} （注意：当调试器执行重新加载时，导入时运行的代码可能会再次执行。为避免这种情况，请尝试仅在模块中使用导入、常量和定义，将所有代码放入函数中。或者，您也可以使用 if __name__=="__main__" 检查。）
  • purpose 该配置覆盖一些按钮的默认行为
    • debug-test，该配置用于调试测试
    • debug-in-terminal，该配置应用与于 Debug Python File in Terminal
  • subProcess 调试子进程，默认为 false，更多参见：multi-target debugging
  • cwd 调试进程的 WorkDir，默认为 ${workspaceFolder}
  • redirectOutput 当设置为 true（internalConsole 的默认值）时，会导致调试器将程序的所有输出打印到 VSCode 调试控制台窗口中。如果设置为 false（integratedTerminal 和 externalTerminal 的默认值），则程序输出不会显示在调试器输出窗口中。
  • justMyCode 默认为 true，将调试仅限于用户编写的代码。设置为 false 还可以启用标准库函数的调试。（建议修改为 false）
  • django 默认为 false，当设置为 true 时，将启用 django 特性，支持 django 模板的调试
  • sudo 默认为 false，当设置为 true 时，会在启动程序是通过 sudo 启动，可以输入密码
  • pyramid 默认为 false，当设置为 true 时，将启用 pyramid 特性
  • gevent 启用 gevent，参见 https://www.gevent.org/intro.html
  • jinja 默认为 false，当设置为 true 时，会启用 Jinja templating engine 的支持
• request 为 attach 相关配置，配置 debug 如何连接到远端
  • connect 配置远端 host 和 port
  • pathMappings 远端代码和本地代码的映射
• logToFile Enable logging of debugger events to a log file.
• showReturnValue 默认为 true，是否展示返回值
• 平台特性配置
  • windows
  • linux
  • osx

测试

VSCode Python 支持 unittest 和 pytest

相关代码

假设我们待测是模块为 inc_dec.py，代码如下：

def increment(x):
    return x + 1

def decrement(x):
    return x - 1

添加 pytest 测试代码 test_pytest.py

import inc_dec    # The code to test


def test_increment():
    assert inc_dec.increment(3) == 4


def test_decrement():
    assert inc_dec.decrement(3) == 4

添加 unittest 测试代码 test_unittest.py

import inc_dec    # The code to test
import unittest   # The test framework


class Test_TestIncrementDecrement(unittest.TestCase):
    def test_increment(self):
        self.assertEqual(inc_dec.increment(3), 4)

    def test_decrement(self):
        self.assertEqual(inc_dec.decrement(3), 4)


if __name__ == '__main__':
    unittest.main()

快速启用测试特性

• 打开测试浏览器，点击 Configuare Python Tests，可以快速配置测试。或者通过 >Python: Configure Tests 命令，也可以配置测试

• 以上选择，都会应用到 python.testing.unittestEnabled 和 python.testing.pytestEnabled 配置项，如果两个框架都启用，那么 Python 扩展将只运行 pytest。当启用测试框架时，如果当前激活的环境中尚不存在框架包，VS Code 会提示您安装该框架包：

运行或调试测试

有很多中运行测试的方法

• 打开测试文件后，选择测试定义行旁边的装订线中显示的绿色运行图标。点击可以直接运行，右击可以选择调试

• 通过如下命令运行测试
  • >Test: Run All Tests 运行所有测试
  • >Test: Run Tests in Current File 运行当前文件的所有测试
  • >Test: Run Test at Cursor 运行光标位置处的测试
• 通过如下命令调试测试
  • >Test: Debug All Tests 调试所有测试
  • >Test: Debug Tests in Current File 调试当前文件的所有测试
  • >Test: Debug Test at Cursor 调试 光标位置处的测试
• 从测试浏览器启动运行
  • 要运行所有发现的测试，请选择测试资源管理器顶部的播放按钮：
  • 要运行一组特定的测试或单个测试，请选择文件、类或测试，然后选择该项目右侧的播放按钮
  • 还可以通过测试资源管理器运行一系列测试。为此，请在要运行的测试上按 Ctrl+单击（或在 macOS 上为 Cmd+单击），右键单击其中一个，然后选择运行测试。

• 从测试浏览器启动调试
  • 要调试所有发现的测试，请选择测试资源管理器顶部的小虫子按钮：
  • 要运行一组特定的测试或单个测试，请选择文件、类或测试，然后选择该项目右侧的小虫子按钮
  • 您还可以通过测试资源管理器运行一系列测试。为此，请在要运行的测试上按 Ctrl+单击（或在 macOS 上为 Cmd+单击），右键单击其中一个，然后选择运行测试。

测试运行后，VS Code 将结果直接在编辑器中显示为装订线装饰。失败的测试也将在编辑器中突出显示，带有显示测试运行错误消息和所有测试运行历史记录的查看视图。您可以按 Escape 关闭视图，可通过 testing.automaticallyOpenPeekView 配置项设置。

另外，关于测试运行的输出，可以在 Python Test Log 输出面板找到。

通过 pytest-xdist 可以支持并发测试，更多参见：官方文档

通过 purpose 字段设置为 "debug-test" 可以为测试的调试添加调试配置，例如

{
    "name": "Python: Current File",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "purpose": ["debug-test"],
    "console": "integratedTerminal",
    "justMyCode": false
}

发现项目的测试

VSCode Python 默认开启了自动测试发现特性（可通过 python.testing.autoTestDiscoverOnSaveEnabled 配置关闭）。

也可以通过测试浏览器的刷新按钮手动刷刷新测试。

如果测试找不到，可能是测试目录没有 __init__.py，没有被识别成 Python 包。

如果有发现失败，可以通过 Python 输出面板查看具体原因

全部测试命令

全部测试配置

VSCode 测试通用配置，按 cmd + ,，搜索 Testing

Python 扩展通用配置

unittest 配置

unittest 的默认参数如下：

• -v 设置 verbosity 级别的输出。删除此参数以获得更简单的输出。
• -s . 指定用于发现测试的起始目录。如果 "test" 文件夹中有测试，请将参数更改为 -s test（在参数数组中表示"-s", "test"）。
• "-p *test*.py" 是用于查找测试的发现模式。在本例中，它是包含单词 test 的任何 .py 文件。如果以不同的方式命名测试文件，例如将 _test 附加到每个文件名，请在数组的相应参数中使用类似 "*_test.py" 的模式。

若要在第一次失败时停止测试运行，请将快速失败选项 "-f" 添加到参数数组中。

关于 unittestArgs 更多参见 unittest command-line interface

pytest 配置

可以通过 pytest.ini 文件配置，更多参见 pytest Configuration.

注意：如果安装了 pytest-cov 覆盖模块，则 VSCode 在调试时不会在断点处停止，因为 pytest-cov 使用相同的技术来访问正在运行的源代码。为防止此行为，请在调试测试时在 pytestArgs 中包含 --no-cov，或者通过将 "env": {"PYTEST_ADDOPTS": "--no-cov"} 添加到您的调试配置中。 （有关更多信息，请参阅 pytest-cov 文档中的调试器和 PyCharm）

交互式 Python

VSCode 支持一个普通的 Python 文件提供 Jupyter Cell 一样的交互式能力。（本文关注的是与 Python 源代码文件有关的特性，更多关于 Jupyter 详细说明，后续会在数据分析专题中讲述）

Python 交互式文件

• 在后缀为 py 的文件，通过特殊注释进行单元格区分 # %%，那么这个文件就会被识别为 Python 交互式文件。

• 点击 Run Cell 会创建一个 Python 交互式窗口

• 识别为 Python 交互式文件可以支持如下快捷键，常见的为

  • Ctrl+Enter Run Cell
  • Shift+Enter Run Cell 并聚焦到下一个单元格，如果不存在将创建一个

• 更多快捷键，参见下表

Python 交互式窗

除了通过上文的方式创建交互是窗口，还可以通过 >Jupyter: Create Interactive Window 命令创建一个交互式窗口。该窗口支持能力

• 自动完成

• Plot Viewer

变量和数据检查

• 变量浏览器

• 变量数据视图

其他 feature

• 连接到远端 Jupyter，通过 Jupyter: Specify local or remote Jupyter server for connections 命令选择，参见：官方文档
• Jupyter notebooks 和 Python 文件相互转换，参见：官方文档
• Debug Jupyter notebook
• Export a Jupyter notebook

全部命令

全部配置

VSCode Docs - Python settings reference

通用配置