# @actions/languageserver 中文文档

规范地址：https://npmcn.com/package/%40actions/languageserver/

版本：0\.3\.61
npm 元数据更新时间：2026-08-04T19:25:31.004Z
中文译文更新时间：2026-11-06T02:16:14.008Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40actions/languageserver
原文对照：https://npmcn.com/package/%40actions/languageserver/?lang=original
项目主页：https://github.com/actions/languageservices#readme
源码仓库：https://github.com/actions/languageservices

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，110 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>= 20
- 运行依赖：7 个
- 首次发布：2023-03-23T21:39:53.742Z
- 最新版本发布：2026-08-04T19:25:30.652Z
- 近 30 天下载量：6596（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 42 个）

## 中文简介

GitHub 动作的语言服务器

## 安装

```sh
npm install @actions/languageserver
```

也可以使用：`pnpm add @actions/languageserver`、`yarn add @actions/languageserver`、`bun add @actions/languageserver`

## README

# 动作/语言服务器

`actions-languageserver` 主机 `actions-languageservice` 并且通过 [语言服务器协议](https://microsoft.github.io/language-server-protocol/) (LSP)作为一个独立的语言服务器.

## 安装

这个 [软件包](https://www.npmjs.com/package/@actions/languageserver) 包含TypeScript类型并编译了ECMAScript模块.

```bash
npm install @actions/languageserver
```

要将语言服务器安装为独立的 CLI :

```bash
npm install -g @actions/languageserver
```

这使得 `actions-languageserver` 命令可在全球范围使用.

## 使用量

### 使用基本使用情况 `vscode-languageserver-node`

对于服务器,请导入模块. 它检测它是在节点.js环境中运行,还是在网络工人中运行,并初始化适当的连接.

`server.ts`数字 :

```typescript
import "@actions/languageserver";
```

为客户端创建新 `LanguageClient` 指向服务器模块.

`client.ts`数字 :

```typescript
import {LanguageClient, ServerOptions, TransportKind} from "vscode-languageclient/node";

const debugOptions = {execArgv: ["--nolazy", "--inspect=6010"]};

const clientOptions: LanguageClientOptions = {
  documentSelector: [{
    pattern: "**/.github/workflows/*.{yaml,yml}"
  }]
};

const serverModule = context.asAbsolutePath(path.join("dist", "server.js"));
const serverOptions: ServerOptions = {
  run: {module: serverModule, transport: TransportKind.ipc},
  debug: {
    module: serverModule,
    transport: TransportKind.ipc,
    options: debugOptions
  }
};

const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);
```

### 从网络工人那里

见 [.../浏览器游戏场](https://npmcn.com/package/%40actions/browser-playground) 例如,将语言服务器托管在网络工人中的执行.

### 提供高级功能

语言服务器接受初始化选项,可用于配置额外的功能. 如果你通过一个github.com `sessionToken`,语言服务将使用 github.com 的数据进行额外的验证,并提供额外的自动补全建议.

```typescript
export interface InitializationOptions {
  /**
   * GitHub token that will be used to retrieve additional information from github.com
   *
   * Requires the `repo` and `workflow` scopes
   */
  sessionToken?: string;

  /**
   * List of repositories that the language server should be aware of
   */
  repos?: RepositoryContext[];

  /**
   * Desired log level
   */
  logLevel?: LogLevel;

  /**
   * Experimental features that are opt-in
   */
  experimentalFeatures?: ExperimentalFeatures;
}
```

通过 `initializationOptions` 页:1 `LanguageClient` 在建立连接时:

```typescript
const clientOptions: LanguageClientOptions = {
  documentSelector: [{
    pattern: "**/.github/workflows/*.{yaml,yml}"
  }],
  initializationOptions: initializationOptions
};

const client = new LanguageClient("actions-language", "GitHub Actions Language Server", serverOptions, clientOptions);
```

### 实验特征

语言服务器通过 `experimentalFeatures` 初始化选项。 这些特性可能在释放之间改变或去除.

```typescript
initializationOptions: {
  experimentalFeatures: {
    // Enable all experimental features
    all: true,

    // Or enable specific features
    missingInputsQuickfix: true,
  }
}
```

**可用的实验特性 :**

| 特性 | 说明 |
| --- | --- |
| `missingInputsQuickfix` | 添加缺少的行动所需输入的代码动作 |
| `blockScalarChompingWarning` | 区块分级时警告(`|` 或者说 `>`) 使用隐含的剪接,这增加了一条可能无意中出现的后遗症新线 |
| `allowBackgroundSteps` | 启用背景工作流程步骤和相关等/取消步骤 |

单个特征旗帜优先 `all`。例如, `{ all: true, missingInputsQuickfix: false }` 允许所有实验特性,但 `missingInputsQuickfix`。 。 。 .

当一个特性毕业生稳定下来时,它的旗帜就会变成不开放的,无论配置值如何,特性都会被启用.

### 独立的CLI

在全球安装后, 您可以直接运行语言服务器 :

```bash
actions-languageserver --stdio
```

这开始语言服务器使用stdio transport,这是编辑器与语言服务器通信的标准方式.

### 在尼奥维姆

#### 1\. 安装语言服务器

```bash
npm install -g @actions/languageserver
```

#### 2\. 设置文件类型检测

将此添加到您的 `init.lua` 检测 GitHub 动作工作流程文件 :

```lua
vim.filetype.add({
  pattern = {
    [".*/%.github/workflows/.*%.ya?ml"] = "yaml.ghactions",
  },
})
```

此设置文件类型为 `yaml.ghactions` 用于 YAML 文件 `.github/workflows/`,允许您在需要时保留单独的YAML LSP配置.

#### 3\. 创建LSP配置

截至 Neovim 011+ 您可以在 `~/.config/nvim/lsp/actionsls.lua`数字 :

```lua
local function get_github_token()
  local handle = io.popen("gh auth token 2>/dev/null")
  if not handle then return nil end
  local token = handle: read("*a"):gsub("%s+", "")
  handle:close()
  return token ~= "" and token or nil
end

local function parse_github_remote(url)
  if not url or url == "" then return nil end

  -- SSH format: git@github.com:owner/repo.git
  local owner, repo = url:match("git@github%.com:([^/]+)/([^/%.]+)")
  if owner and repo then
    return owner, repo: gsub("%.git$", "")
  end

  -- HTTPS format: https://github.com/owner/repo.git
  owner, repo = url:match("github%.com/([^/]+)/([^/%.]+)")
  if owner and repo then
    return owner, repo:gsub("%.git$", "")
  end

  return nil
end

local function get_repo_info(owner, repo)
  local cmd = string.format(
    "gh repo view %s/%s --json id,owner --template '{{.id}}\t{{.owner.type}}' 2>/dev/null",
    owner,
    repo
  )
  local handle = io.popen(cmd)
  if not handle then return nil end
  local result = handle: read("*a"):gsub("%s+$", "")
  handle:close()

  local id, owner_type = result:match("^(%d+)\t(.+)$")
  if id then
    return {
      id = tonumber(id),
      organizationOwned = owner_type == "Organization",
    }
  end
  return nil
end

local function get_repos_config()
  local handle = io.popen("git rev-parse --show-toplevel 2>/dev/null")
  if not handle then return nil end
  local git_root = handle: read("*a"):gsub("%s+", "")
  handle:close()

  if git_root == "" then return nil end

  handle = io.popen("git remote get-url origin 2>/dev/null")
  if not handle then return nil end
  local remote_url = handle:read("*a"):gsub("%s+", "")
  handle:close()

  local owner, name = parse_github_remote(remote_url)
  if not owner or not name then return nil end

  local info = get_repo_info(owner, name)

  return {
    {
      id = info and info.id or 0,
      owner = owner,
      name = name,
      organizationOwned = info and info.organizationOwned or false,
      workspaceUri = "file://" .. git_root,
    },
  }
end

return {
  cmd = { "actions-languageserver", "--stdio" },
  filetypes = { "yaml.ghactions" },

  -- `root_dir` ensures that the LSP does not attach to all yaml files
  root_dir = function(bufnr, on_dir)
    local parent = vim.fs.dirname(vim.api.nvim_buf_get_name(bufnr))
    if
      vim.endswith(parent, '/.github/workflows')
      or vim.endswith(parent, '/.forgejo/workflows')
      or vim.endswith(parent, '/.gitea/workflows')
    then
      on_dir(parent)
    end
  end,

  init_options = {
    -- Optional: provide a GitHub token and repo context for added functionality
    -- (e.g., repository-specific completions)
    sessionToken = get_github_token(),
    repos = get_repos_config(),
  },

  -- allow the lsp to register capabilities on demand
  capabilities = {
    workspace = {
      didChangeWorkspaceFolders = {
        dynamicRegistration = true,
      },
    },
  },

  -- given a file:// protocol path as built using the workspaceUri above,
  -- resolve path to disk path and provide filecontents when lsp requests this
  -- action https://github.com/actions/languageservices/blob/main/languageserver/src/request.ts#L2
  -- taken from https://github.com/neovim/nvim-lspconfig/blob/75e49cfa588a89ca667d767c0afef3ceac205faa/lsp/gh_actions_ls.lua#L33-L48
  handlers = {
    ["actions/readFile"] = function(_, result)
      if type(result.path) ~= "string" then
        return nil, nil
      end
      local file_path = vim.uri_to_fname(result.path)
      if vim.fn.filereadable(file_path) == 1 then
        local f = assert(io.open(file_path, "r"))
        local text = f:read("*a")
        f:close()

        return text, nil
      end
      return nil, nil
    end,
  },
}
```

#### 4\. 启用LSP

添加到您的 `init.lua`数字 :

```lua
vim.lsp.enable('actionsls')
```

#### 5\. 核实它是否有效

打开任意 `.github/workflows/*.yml` 文件并运行 :

```vim
:checkhealth vim.lsp
```

你应该看看 `actionsls` 在所附客户列表中.

## 捐款

见 [捐款额](https://npmcn.com/package/%40actions/CONTRIBUTING.md) 作为一般准则和建议存放处的基础.

如果你想捐款,请跑 [更美丽](https://prettier.io/) 用于格式化您的代码,并在提交您的PR前酌情添加单位测试.

### 构建

```bash
npm run build
```

或监视更改

```bash
npm run watch
```

### 本地运行语言服务器

运行后

```bash
npm run build:cli
npm link
```

`actions-languageserver` 将在全球范围内提供。 你可以从以下开始:

```bash
actions-languageserver --stdio
```

一旦链接,您也可以观看更改并自动重建:

```bash
npm run watch:cli
```

### 测试

```bash
npm test
```

或监视更改和运行测试:

```bash
npm run test-watch
```

### 林特

```bash
npm run format-check
```

## 许可证

这个项目根据麻省理工学院开源许可证的规定获得许可. 请参考 [麻省理工学院](https://npmcn.com/package/%40actions/LICENSE) 全部条件.

## 常见问题

### @actions/languageserver 是什么？

GitHub 动作的语言服务器

### 如何安装 @actions/languageserver？

在项目目录运行 npm install @actions/languageserver，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 actions-languageserver，可以用 npx actions-languageserver 直接运行。

### @actions/languageserver 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/actions\_\_languageserver 是否存在。

### @actions/languageserver 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @actions/languageserver 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @actions/languageserver 可以商用吗？

@actions/languageserver 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @actions/languageserver 的下载量有多少？

根据 npm 官方下载统计，@actions/languageserver 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,596 次，日均约 220 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @actions/languageserver 还在维护吗？

最新版本 0\.3\.61 发布于 2026/08/05（3 个月前）；至今共发布 63 个版本，其中过去 12 个月发布了 42 个；首次发布于 2023/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。