【源码共读】第44期 | 神器啊，从未想过 VSCode 还能这样直接打开仓库URL，原理揭秘~-五八三

1. 前言

本文参加了由公众号@若川视野 发起的每周源码共读活动， 点击了解详情一起参与。
这是源码共读的第44期，链接：神器啊，从未想过 VSCode 还能这样直接打开仓库URL，原理揭秘~
依赖的插件仓库
antfu仓库
若川仓库

2. 插件功能

Open in GitHub 插件也提供了一些用户自定义配置。支持配置为自己的域名，比如 gitlab，配置好后就能打开相应的项目地址。

配置：

也可以在项目中新增 .vscode/setting.json 配置。

{

  "openInGitHub.github.domain": "github.com", // Custom GitHub domain
  "openInGitHub.remote.name": "origin", // Name of the remote repository
  "openInGitHub.remote.branch": "master", // Name of the remote branch
  "openInGitHub.useLocalBranch": true, // Use the local branch instead of the fixed remote branch
  "openInGitHub.useLocalRange": true, // Highlight the local selection range, if there's one
  "openInGitHub.useLocalLine": false // Highlight the local line if there's no selection range
}

除了包含打开项目的命令，还包含了其他很多命令，比如打开 issue、action、pull request、release 等，可以按快捷键：ctrl + shift + p 输入 >open in github 查看。

3. vscode-open-in-github-button项目解析

3.1 依赖解析

根据您提供的插件列表，以下是每个插件的简要说明和用法：

“@antfu/eslint-config”: 这是一个 ESLint 配置文件，用于定义 JavaScript/TypeScript 代码的静态分析规则
“@antfu/ni”: 这是一个开发工具集合，用于开发 Vue.js 应用程序。它提供了一组命令行工具和工程化配置，帮助您更方便地构建和调试 Vue.js 项目。
“@types/node”: Node.js 的声明文件
“@types/vscode”: VS Code 的声明文件
“bumpp”: 这是一个版本管理工具，用于自动化处理项目中的版本号更新和发布流程。您可以使用该工具来简化版本控制操作，如自动增加版本号、生成 changelog 等。
“eslint”: 这是一个 JavaScript/TypeScript 代码静态分析工具
“esno”: 这是一个命令行工具，用于运行含有 ES 模块的脚本。它支持使用 import/export 语法运行 ES 模块，并提供了一些额外的功能，如类型检查等。
“pnpm”: 这是一个包管理器，类似于 npm 和 yarn。它旨在提供更快的安装速度和更高的磁盘空间利用率。您可以使用 pnpm 来安装、更新和管理项目依赖项。
“rimraf”: 这是一个用于删除文件和文件夹的工具。它是对 Node.js 内置的 fs.unlink 和 fs.rmdir 方法的封装，能够跨平台地删除文件和文件夹。
“tsup”: 这是一个用于构建 TypeScript 库和应用程序的打包工具。它可以将您的 TypeScript 代码转换为可在浏览器或 Node.js 环境中运行的 JavaScript 代码。
“typescript”: 这是一个用于编写 TypeScript 代码的编译器和语言服务。
“vite”: 这是一个快速开发工具，用于构建现代化的前端项目。它通过利用原生 ES 模块的特性来提供快速的热模块重载和开发体验。
“vitest”: 这是一个用于测试 Vue.js 应用程序的工具集合。它提供了一套 API 和辅助函数，使您能够编写和运行单元测试和集成测试。
“vsce”: 这是一个用于开发和发布 VS Code 扩展的命令行工具。您可以使用它来打包、发布和管理您的扩展程序。

3.2 scripts命令说明

{

    "scripts": {
        // 用 tsup 打包 vscode 插件扩展
        "build": "tsup src/index.ts --external vscode",
        // 开发
        "dev": "nr build --watch",
        "lint": "eslint .",
        // 预发布
        "vscode:prepublish": "nr build",
        // 发布，不包含依赖
        "publish": "vsce publish --no-dependencies",
        // 打包，不包含依赖
        "pack": "vsce package --no-dependencies",
        // 测试
        "test": "vitest",
        // type 检测
        "typecheck": "tsc --noEmit",
        // 发布
        "release": "bumpp && nr publish"
    }
}

3.3 github actions

项目配置了yml脚本，来看下 github actions 配置。了解 GitHub Actions

一个开源项目，一般会有基础的 workflow。

ci 每次 git push 命令时自动执行 lint 和 test 等，保证校验通过。
release：每次检测到 git tag，就自动发一个包。

文件位置在.vscode/workflows下，以yml/yaml后缀结尾:

ci:

name: CI






on:
 push:
   branches:
     - main

 pull_request:
   branches:
     - main

jobs:
 lint:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3


     - name: Install pnpm
       uses: pnpm/action-setup@v2

     - name: Set node
       uses: actions/setup-node@v3
       with:
         node-version: 16.x
         cache: pnpm


     - name: Setup
       run: npm i -g @antfu/ni


     - name: Install
       run: nci

     - name: Lint
       run: nr lint

 typecheck:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3

     - name: Install pnpm
       uses: pnpm/action-setup@v2

     - name: Set node
       uses: actions/setup-node@v3
       with:
         node-version: 16.x
         cache: pnpm

     - name: Setup
       run: npm i -g @antfu/ni

     - name: Install
       run: nci

     - name: Typecheck
       run: nr typecheck

 test:
   runs-on: ${{ matrix.os }}

   strategy:
     matrix:
       node: [16.x]
       os: [ubuntu-latest, windows-latest, macos-latest]
     fail-fast: false

   steps:
     - uses: actions/checkout@v3

     - name: Install pnpm
       uses: pnpm/action-setup@v2

     - name: Set node version to ${{ matrix.node }}
       uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node }}
         cache: pnpm

     - name: Setup
       run: npm i -g @antfu/ni

     - name: Install
       run: nci

     - name: Build
       run: nr build

     - name: Test
       run: nr test

具体解释：

GitHub Actions 设置的 CI 配置文件。该配置文件定义了三个jobs（lint、typecheck 和 test），它们在不同的事件触发条件下执行。

触发条件：当进行 push 或 pull request 操作，并且分支为 main 时触发。

lint ：在 Ubuntu 环境下运行，执行以下步骤：
1. 使用 actions/checkout@v3 动作来检出代码库。
2. 使用 pnpm/action-setup@v2 动作安装 pnpm 包管理器。
3. 使用 actions/setup-node@v3 动作设置 Node.js 运行时环境，并缓存 pnpm。
4. 使用 npm i -g @antfu/ni 命令全局安装 @antfu/ni 工具。
5. 使用 nci 命令安装项目依赖。
6. 使用 nr lint 命令运行 lint 检查。
typecheck ：在 Ubuntu 环境下运行，执行以下步骤：
1. 使用 actions/checkout@v3 动作来检出代码库。
2. 使用 pnpm/action-setup@v2 动作安装 pnpm 包管理器。
3. 使用 actions/setup-node@v3 动作设置 Node.js 运行时环境，并缓存 pnpm。
4. 使用 npm i -g @antfu/ni 命令全局安装 @antfu/ni 工具。
5. 使用 nci 命令安装项目依赖。
6. 使用 nr typecheck 命令运行类型检查。
test ：在多个操作系统下运行测试。该作业根据 matrix 中定义的 node 和 os 参数进行配置，并执行以下步骤：
1. 使用 actions/checkout@v3 动作来检出代码库。
2. 使用 pnpm/action-setup@v2 动作安装 pnpm 包管理器。
3. 使用 actions/setup-node@v3 动作设置 Node.js 运行时环境，并缓存 pnpm。
4. 使用 npm i -g @antfu/ni 命令全局安装 @antfu/ni 工具。
5. 使用 nci 命令安装项目依赖。
6. 使用 nr build 命令进行构建。
7. 使用 nr test 命令运行测试。

效果：

以lint为例，需要运行的步骤：

release:

name: Release






permissions:
 contents: write

on:
 push:
   tags:
     - 'v*'



jobs:
 release:
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3
       with:
         fetch-depth: 0


     - uses: actions/setup-node@v3
       with:
         node-version: 16.x


     - run: npx changelogithub
       env:
         GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

配置文件说明：

触发条件：在推送（push）带有以 ‘v’ 开头的标签（tags）时发布新版本。

permissions 部分：该部分指定了 GitHub Actions 需要的权限。具体来说，它声明了对内容（contents）的写入权限，用于创建发布。
on 部分：该部分指定了触发该工作流程的事件条件。在本例中，当推送的标签（tags）以 ‘v’ 开头时触发发布。
jobs 部分：该部分定义了一个名为 release 的job。在 Ubuntu 环境下运行，并执行以下步骤：
1. 使用 actions/checkout@v3 动作来检出代码库，同时通过设置 fetch-depth: 0 来获取完整的提交历史。
2. 使用 actions/setup-node@v3 动作设置 Node.js 运行时环境，并指定使用 16.x 版本。
3. 使用 npx changelogithub 命令生成变更日志，并结合环境变量 GITHUB_TOKEN 提供的 GitHub 访问令牌来与 GitHub API 进行交互。这将自动创建一个新的发布，并将生成的变更日志附加到该发布上。

注意GITHUB_TOKEN需要自己创建写入：

效果：

3.4 测试vitest

源码只是写了一个简单的测试。

// test/index.test.ts
import { describe, expect, it } from 'vitest'

describe('should', () => {
  it('exported', () => {
    expect(1).toEqual(1)
  })
})

3.5 入口文件src/index.ts

import { StatusBarAlignment, window } from 'vscode'






export function activate() {
  //创建一个新的状态栏项，并指定对齐方式（`StatusBarAlignment.Left`）和优先级（0）
  const statusBar = window.createStatusBarItem(StatusBarAlignment.Left, 0)
  //点击状态栏项时要执行的操作,
  statusBar.command = 'openInGitHub.openProject'
  //状态栏项的文本内容为 `$(github)`，这是一个内置的图标标识符，代表着 GitHub 图标。
  statusBar.text = '$(github)'
  //在鼠标悬停在状态栏项上时显示的提示文本
  statusBar.tooltip = 'Open in GitHub'
  //状态栏项显示在 VS Code 的状态栏上
  statusBar.show()
}

点击状态栏的 open in github 按钮，其实执行的是 'openInGitHub.openProject' 命令。

是由package.json中依赖的插件提供：

 "extensionPack": [
    "fabiospampinato.vscode-open-in-github"
  ],

4. vscode-open-in-github项目解析

4.1 依赖命令

依赖说明：

absolute：生成指定路径的绝对路径。
find-up：从指定位置向上递归查找指定文件或目录。
json5：解析和字符串化 JSON5 格式的数据。
lodash：实用工具库，提供了许多常用的函数方法。
mkdirp：递归创建目录。
pify：将回调风格的函数转换为返回 Promise 的函数。
simple-git：简化 Git 命令操作的库。

scripts命令：

 "scripts": {
     //在发布扩展之前的预处理脚本。首先删除 `out` 目录，使用 Webpack 进行生产模式的打包
    "vscode:prepublish": "rm -rf out && webpack --mode production",
    //使用 `vsce` 工具将扩展发布到VS Code扩展市场，使用`npm publish`发布到npm
    "publish": "vsce publish && npm publish",
    //以开发模式编译代码的脚本。它使用 Webpack 进行打包，配置为开发模式
    "compile": "webpack --mode development",
    //通过添加 `--watch` 参数使 Webpack 在源文件发生变化时自动重新编译
    "compile:watch": "webpack --mode development --watch",
    //在安装依赖后执行的脚本。用于运行 VS Code 的安装脚本，确保相关的依赖项正确安装和配置
    "postinstall": "node ./node_modules/vscode/bin/install",
    //运行 VS Code 的测试脚本，用于执行项目的单元测试
    "test": "node ./node_modules/vscode/bin/test"
  },

4.2 源码调试分析

1.调试

需要安装Debug Launcher,运行Debug Launcher:Auto

2.项目结构

src
├─commands.ts //
├─config.ts //
├─extension.ts // 入口文件
├─url.ts   //
└utils.ts  //

3.文件调试说明

extension.ts: 主要进行命令注册

/* IMPORT */






import Utils from './utils';


/* ACTIVATE */

const activate = Utils.initCommands;


/* EXPORT */



export {activate};

utils.ts:注册命令

// package.json
 "contributes": {
    "configuration": {
    "commands": [
      {
        "command": "openInGitHub.openProject",
        "title": "Open in GitHub: Project"
      },
      {
        "command": "openInGitHub.openFile",
        "title": "Open in GitHub: File"
      },
      {
        "command": "openInGitHub.openFileHistory",
        "title": "Open in GitHub: File History"
      },
      {
        "command": "openInGitHub.openFileBlame",
        "title": "Open in GitHub: File Blame"
      },
      {
        "command": "openInGitHub.openFilePermalink",
        "title": "Open in GitHub: File Permalink"
      },
      {
        "command": "openInGitHub.openIssues",
        "title": "Open in GitHub: Issues"
      },
      {
        "command": "openInGitHub.openPullRequests",
        "title": "Open in GitHub: Pull Requests"
      },
      {
        "command": "openInGitHub.openReleases",
        "title": "Open in GitHub: Releases"
      },
      {
        "command": "openInGitHub.openActions",
        "title": "Open in GitHub: Actions"
      },
      {
        "command": "openInGitHub.openProjects",
        "title": "Open in GitHub: Projects"
      },
      {
        "command": "openInGitHub.openWiki",
        "title": "Open in GitHub: Wiki"
      },
      {
        "command": "openInGitHub.openSettings",
        "title": "Open in GitHub: Settings"
      },
      {
        "command": "openInGitHub.copyFilePermalink",
        "title": "Open in GitHub: Copy File Permalink"
      }
    ]
  },

const Utils = {
  // 初始化命令
  initCommands ( context: vscode.ExtensionContext ) {
    //1. 通过 `getExtension` 方法获取扩展的信息，并获取package.json中贡献的命令列表
    const {commands} = vscode.extensions.getExtension ( 'fabiospampinato.vscode-open-in-github' ).packageJSON.contributes;
    // 2. 使用 `forEach` 循环遍历命令列表的每一项。对于每个命令项：
    commands.forEach ( ({ command, title }) => {
      // 2.1 从 `Commands` 对象中取得与命令名称对应的处理函数 `handler`
      const commandName = _.last ( command.split ( '.' ) ) as string,
            handler = Commands[commandName],
            //2.2 使用 `vscode.commands.registerCommand` 方法注册命令，并将处理函数绑定到该命令
            disposable = vscode.commands.registerCommand ( command, () => handler () );


      context.subscriptions.push ( disposable );


    });


    return Commands;

  },
}

command.ts

function openProject () {






  return URL.open ();


}

url.ts

// open
 async open(file = false, permalink = false, page?) {
    //将获取到的 URL 使用 vscode.Uri.parse 方法解析为一个 vscode.Uri 对象
    const url = await URL.get(file, permalink, page);
    //使用 vscode.env.openExternal 方法打开该 URL，实现在 VS Code 外部打开指定的链接
    vscode.env.openExternal(vscode.Uri.parse(url));
  }
  
  
  // get 获取git地址 如果config有自定义域名，则使用config中定义的
  async get ( file = false, permalink = false, page? ) {
    const repopath = await Utils.repo.getPath ();


    const git = Utils.repo.getGit ( repopath ),
          repourl = await Utils.repo.getUrl ( git );
          
    const config = Config.get ();


    let filePath = '',
        branch = '',
        lines = '',
        hash = '';
    // ... 省略部分代码
    branch = encodeURIComponent ( branch );
    filePath = encodeURIComponent ( filePath ).replace ( /%2F/g, '/' );
    const url = _.compact ([ repourl, page, branch, hash, filePath, lines ]).join ( '/' );

    return url;


  },

config.ts

const Config = {






  get ( extension = 'openInGitHub' ) {
  //  `get(extension)`：该方法用于获取扩展配置。
  //它通过调用 `vscode.workspace.getConfiguration()` 方法获取当前工作区的配置，并传入  扩展名称 `extension`（默认为 `"openInGitHub"`）进行筛选。
  // 然后使用 `.get(extension)` 方法获取相应的配置项。
    return vscode.workspace.getConfiguration ().get ( extension ) as any;


  }



};

扩展配置项定义：

    "configuration": {
      "type": "object",
      "title": "Open in GitHub - Configuration",
      "properties": {
        "openInGitHub.github.domain": {
          "type": "string",
          "description": "Custom GitHub domain",
          "default": "github.com"
        },
        "openInGitHub.remote.name": {
          "type": "string",
          "description": "Name of the remote repository",
          "default": "origin"
        },
        "openInGitHub.remote.branch": {
          "type": "string",
          "description": "Name of the remote branch",
          "default": "master"
        },
        "openInGitHub.useLocalBranch": {
          "type": "boolean",
          "description": "Use the local branch instead of the fixed remote branch",
          "default": true
        },
        "openInGitHub.useLocalRange": {
          "type": "boolean",
          "description": "Highlight the local selection range, if there's one",
          "default": true
        },
        "openInGitHub.useLocalLine": {
          "type": "boolean",
          "description": "Highlight the local line if there's no selection range",
          "default": false
        }
      }
    },

整体流程如下：

入口文件调用Utils.initCommands（读取package.json中的commands数组），使用 vscode.commands.registerCommand ( command, () => handler () ) 进行批量注册 openProject 命令
调用Commands.openProject函数
调用 URL.open() 函数 打开使用vscode.env.openExternal ( vscode.Uri.parse ( url ) );
- 实际调用的是 URL.get 函数,
  - Utils.repo.getPath
  - Utils.repo.getUrl
- 先根据 vscode 的能力，获取到仓库的路径
- 再根据仓库的路径，获取 git 实例（simple-git）
- 根据 git 实例，获取到仓库的 url