copilot.lua

此插件是 github/copilot.vim 的纯 Lua 替代方案。 非常感谢 @tris203 提供的 NES 功能背后的代码（copilot-lsp）。

目录

• 要求
• 安装
  • 认证
    • 使用其他 GitHub 实例进行认证
• 设置与配置
  • 面板
  • 建议
  • 高亮组
  • 文件类型
  • 日志记录器
  • copilot_node_command
  • server_opts_overrides
  • 工作区文件夹
  • 根目录
  • should_attach
  • 服务器
• 命令
• 集成
• 常见问题解答

要求

• Curl
• NeoVim 0.11.0 或更高版本
• 如果使用默认的 Node.js LSP 版本，则需要 NodeJS v22 或更高版本

安装

使用你喜欢的插件管理器安装该插件。 例如，使用 packer.nvim：

use { "zbirenbaum/copilot.lua"
  requires = {
    "copilotlsp-nvim/copilot-lsp", -- (可选) 用于 NES 功能
  },
}

认证

你可以使用以下方法之一进行认证：

:Copilot auth signout

:Copilot auth signin

:Copilot auth info

使用其他 GitHub 实例进行认证

如果你的 Copilot 访问权限不是由公共 GitHub 实例提供的，你可以将认证提供商设置为自定义 URL，并使用相应的配置键，例如： auth_provider_url = "https://mycorp.ghe.com/"。

设置与配置

你需要运行 require("copilot").setup(options) 函数才能启动 Copilot。 如果没有提供选项，则使用默认值。

由于 Copilot 服务器需要一些时间才能启动，建议你延迟加载 Copilot。 例如：

use {
  "zbirenbaum/copilot.lua",
  requires = {
    "copilotlsp-nvim/copilot-lsp", -- (可选) 用于 NES 功能
  },
  cmd = "Copilot",
  event = "InsertEnter",
  config = function()
    require("copilot").setup({})
  end,
}

require('copilot').setup({
  panel = {
    enabled = true,
    auto_refresh = false,
    keymap = {
      jump_prev = "[[",
      jump_next = "]]",
      accept = "<CR>",
      refresh = "gr",
      open = "<M-CR>"
    },
    layout = {
      position = "bottom", -- | top | left | right | bottom |
      ratio = 0.4
    },
  },
  suggestion = {
    enabled = true,
    auto_trigger = false,
    hide_during_completion = true,
    debounce = 15,
    trigger_on_accept = true,
    keymap = {
      accept = "<M-l>",
      accept_word = false,
      accept_line = false,
      next = "<M-]>",
      prev = "<M-[>",
      dismiss = "<C-]>",
      toggle_auto_trigger = false,
    },
  },
  nes = {
    enabled = false, -- 需要 copilot-lsp 作为依赖
    auto_trigger = false,
    keymap = {
      accept_and_goto = false,
      accept = false,
      dismiss = false,
    },
  },
  auth_provider_url = nil, -- 认证提供商的 URL，如果不是 "https://github.com/"
  logger = {
    file = vim.fn.stdpath("log") .. "/copilot-lua.log",
    file_log_level = vim.log.levels.OFF,
    print_log_level = vim.log.levels.WARN,
    trace_lsp = "off", -- "off" | "debug" | "verbose"
    trace_lsp_progress = false,
    log_lsp_messages = false,
  },
  copilot_node_command = 'node', -- Node.js 版本必须大于 22
  workspace_folders = {},
  copilot_model = "",
  disable_limit_reached_message = false,  -- 设置为 `true` 可以抑制完成次数达到上限的弹出窗口
  root_dir = function()
    return vim.fs.dirname(vim.fs.find(".git", { upward = true })[1])
  end,
  should_attach = function(buf_id, _)
    if not vim.bo[buf_id].buflisted then
      logger.debug("不附加，缓冲区未列出")
      return false
    end

    if vim.bo[buf_id].buftype ~= "" then
      logger.debug("不附加，缓冲区类型为 " .. vim.bo[buf_id].buftype)
      return false
    end

    return true
  end,
  server = {
    type = "nodejs", -- "nodejs" | "binary"
    custom_server_filepath = nil,
  },
  server_opts_overrides = {},
})

面板

面板可用于在分屏窗口中预览建议。你可以运行 :Copilot panel 命令来打开它。

如果 auto_refresh 设置为 true, 则会在你输入内容时自动刷新建议。

copilot.panel 模块提供了以下函数：

require("copilot.panel").accept()
require("copilot.panel").jump_next()
require("copilot.panel").jump_prev()
require("copilot.panel").open({position, ratio})
require("copilot.panel").close()
require("copilot.panel").toggle()
require("copilot.panel").refresh()
require("copilot.panel").is_open()

这些函数也可以通过 :Copilot panel <function> 命令访问（例如：:Copilot panel accept）。

建议

当 auto_trigger 为 true 时，Copilot 会在您进入插入模式后立即开始提供建议。
当 auto_trigger 为 false 时，您可以使用 next、prev 或 accept 键映射来触发 Copilot 的建议。
当 trigger_on_accept 为 false 时，按键输入将原样传递到缓冲区，而不会触发补全。

要切换当前缓冲区的自动触发功能，可以使用 require("copilot.suggestion").toggle_auto_trigger()。

当 popupmenu-completion 打开时，Copilot 的建议会自动隐藏。如果您使用自定义的补全菜单，可以通过将 copilot_suggestion_hidden 缓冲区变量设置为 true 来实现相同的行为。

cmp.event:on("menu_opened", function()
  vim.b.copilot_suggestion_hidden = true
end)

cmp.event:on("menu_closed", function()
  vim.b.copilot_suggestion_hidden = false
end)

vim.api.nvim_create_autocmd("User", {
  pattern = "BlinkCmpMenuOpen",
  callback = function()
    vim.b.copilot_suggestion_hidden = true
  end,
})

vim.api.nvim_create_autocmd("User", {
  pattern = "BlinkCmpMenuClose",
  callback = function()
    vim.b.copilot_suggestion_hidden = false
  end,
})

copilot.suggestion 模块提供了以下函数：

require("copilot.suggestion").is_visible()
require("copilot.suggestion").accept(modifier)
require("copilot.suggestion").accept_word()
require("copilot.suggestion").accept_line()
require("copilot.suggestion").next()
require("copilot.suggestion").prev()
require("copilot.suggestion").clear_preview()
require("copilot.suggestion").update_preview()
require("copilot.suggestion").dismiss()
require("copilot.suggestion").toggle_auto_trigger()

这些函数也可以通过 :Copilot suggestion <function> 命令访问（例如：:Copilot suggestion accept）。

高亮组

Copilot 使用两个高亮组来样式化其建议：

如果您的颜色方案未定义这些高亮组，它们将默认链接到 Comment。要自定义它们，请在颜色方案加载 之后 设置高亮，或使用 ColorScheme 自动命令：

vim.api.nvim_create_autocmd("ColorScheme", {
  callback = function()
    vim.api.nvim_set_hl(0, "CopilotSuggestion", { fg = "#83a598", italic = true })
    vim.api.nvim_set_hl(0, "CopilotAnnotation", { fg = "#83a598" })
  end,
})

nes（下一个编辑建议）

[!警告]
此功能仍处于实验阶段，在某些场景下可能无法正常工作，请报告您遇到的任何问题。

当 enabled 为 true 时，Copilot 将通过 copilot-lsp 根据您接下来可能进行的编辑提供建议。如果没有建议，键映射将直接传递原始按键。

copilot-lsp 还内置了一些配置项，更多配置请参考 copilot-lsp 文档。这些配置应在 copilot-lsp 依赖的 init 函数中设置。

use {
  "zbirenbaum/copilot.lua",
  requires = {
    "copilotlsp-nvim/copilot-lsp",
    init = function()
      vim.g.copilot_nes_debounce = 500
    end,
  },
  cmd = "Copilot",
  event = "InsertEnter",
  config = function()
    require("copilot").setup({
      nes = {
        enabled = true,
        keymap = {
          accept_and_goto = "<leader>p",
          accept = false,
          dismiss = "<Esc>",
        },
      },
    })
  end,
}

文件类型

指定要附加 Copilot 的文件类型。

示例：

require("copilot").setup {
  filetypes = {
    markdown = true, -- 覆盖默认值
    terraform = false, -- 禁用特定文件类型
    sh = function ()
      if string.match(vim.fs.basename(vim.api.nvim_buf_get_name(0)), '^%.env.*') then
        -- 对 .env 文件禁用
        return false
      end
      return true
    end,
  },
}

如果您添加 "*" 作为文件类型，则不再使用 filetypes 的默认配置。例如：

require("copilot").setup {
  filetypes = {
    javascript = true, -- 允许特定文件类型
    typescript = true, -- 允许特定文件类型
    ["*"] = false, -- 禁用所有其他文件类型，并忽略默认的 `filetypes`
  },
}

日志记录

日志级别达到或高于 file_log_level 的内容将被写入 file。
日志级别达到或高于 print_log_level 的内容将通过 NeoVim 的 notify 功能打印出来。
要关闭其中任一项，只需将其级别设置为 vim.log.levels.OFF。
文件日志是异步进行的，以尽量减少对性能的影响，但仍会带来一定的开销。

日志级别采用 vim.log 中定义的级别：

vim.log = {
  levels = {
    TRACE = 0,
    DEBUG = 1,
    INFO = 2,
    WARN = 3,
    ERROR = 4,
    OFF = 5,
  },
}

trace_lsp 控制 LSP 跟踪消息（$/logTrace）的日志记录，可设置为：

• off
• messages：输出 LSP 消息
• verbose：在消息中添加更多信息。

当 trace_lsp_progress 为 true 时，LSP 进度消息（$/progress）也会被记录。
当 log_lsp_messages 为 true 时，LSP 日志消息（window/logMessage）事件会被记录。

请注意，开启所有日志功能可能会导致日志文件随着时间推移变得非常庞大，且应用程序不会对其进行清理。

copilot_node_command

使用此字段指定特定 Node.js 版本的路径，例如由 nvm 安装的版本。Node.js 版本必须为 22 或更高。

示例：

copilot_node_command = vim.fn.expand("$HOME") .. "/.config/nvm/versions/node/v22.0.0/bin/node", -- Node.js 版本必须 > 22

server_opts_overrides

覆盖 Copilot LSP 客户端设置。有关选项列表，请参阅 :h vim.lsp.start。
请确保不要覆盖 name 字段，因为该字段用于效率优化，在多项检查中用于验证 Copilot 是否正在运行。

settings 字段可用于自定义 Copilot LSP 的行为。完整可用设置及其键名请参阅 SettingsOpts.md。

示例：

require("copilot").setup {
  server_opts_overrides = {
    trace = "verbose",
    settings = {
      advanced = {
        listCount = 10, -- 面板中的补全数量
        inlineSuggestCount = 3, -- getCompletions 中的补全数量
      }
    },
  }
}

[!注意]
settings 的值遵循与 SettingsOpts.md 中键名匹配的嵌套表结构。
例如，InlineSuggestCount: ["advanced", "inlineSuggestCount"] 将变为 settings = { advanced = { inlineSuggestCount = 3 } }。

workspace_folders

工作区文件夹可以提升 Copilot 的代码建议质量。 默认情况下，root_dir 会被用作 workspace_folder。

可以通过配置添加额外的文件夹，如下所示：

workspace_folders = {
  "/home/user/gits",
  "/home/user/projects",
}

也可以在运行时通过命令 :Copilot workspace add [folderpath] 添加，其中 [folderpath] 是要添加的工作区文件夹路径。

root_dir

此选项允许更改用于获取根目录的函数。默认行为是查找包含 .git 文件夹的父目录；如果未找到，则使用当前工作目录。

should_attach

此函数用于决定 Copilot 是否应附加到当前缓冲区。如果你希望超越仅基于文件类型的判断，而对 Copilot 的附加时机有更精细的控制，这个选项会非常有用。你还可以通过省略该函数中的相关部分，使 Copilot 附加到已列出的缓冲区。由于此检查发生在 Copilot 附加到缓冲区之前，因此可以有效防止 Copilot 读取敏感文件。

例如：

require("copilot").setup {
  should_attach = function(_, bufname)
    if string.match(bufname, "env") then
      return false
    end

    return true
  end
}

server

[!CAUTION] "binary" 模式目前仍处于实验阶段，请报告你遇到的任何问题。

type 可以是 "nodejs" 或 "binary"。如果选择 "binary"，系统将自动下载对应的二进制文件。

custom_server_filepath 用于指定服务器路径（包括文件名），如果是 "nodejs" 模式，则指向 JavaScript 文件；如果是 "binary" 模式，则指向二进制文件。如果该文件可通过你的 PATH 访问，也可以直接指定文件名。

当使用 "binary" 模式时，下载过程将被禁用，直接使用二进制文件。示例：

require("copilot").setup {
  server = {
    type = "nodejs",
    custom_server_filepath = "/home/user/copilot-lsp/language-server.js",
  },
}

命令

copilot.lua 定义了 :Copilot 命令，可用于执行各种操作。该命令支持自动补全，请尝试使用。

集成

copilot.api 模块可用于在 copilot.lua 的基础上构建集成。

• zbirenbaum/copilot-cmp：与 nvim-cmp 的集成。
• giuxtaposition/blink-cmp-copilot：与 blink.cmp 的集成。
• fang2hou/blink-copilot：与 blink.cmp 的集成，但有一些差异。
• AndreM222/copilot-lualine：与 lualine.nvim 的集成。

常见问题解答

证书解析错误

这是 Copilot LSP 本身的问题，详情请参阅 此讨论。请将插件更新至最新版本以解决此问题。如果更新后问题仍未解决，有用户反馈称更新 /usr/bin/update-ca-trust 并移除信任提取命令中的 --comment 选项可以解决问题。不过，此方法尚未经过本插件作者验证，可能存在意外后果，请谨慎操作。

多个偏移编码警告

如 #247 中所述，该问题出现的原因是两个或多个客户端使用了不同的偏移编码。要解决这个问题，在 lspconfig 中进行如下设置：

local capabilities = vim.lsp.protocol.make_client_capabilities() -- 获取能力
capabilities.general.positionEncodings = { "utf-16" } -- 设置偏移编码，更多信息请参考 `:h vim.lsp.start`
require("lspconfig")[server].setup({ capabilities = capabilities }) -- 设置服务器

同样地，在 Copilot 的 server_opts_overrides 中也进行设置：

server_opts_overrides = {
  offset_encoding = "utf-16" -- 设置与上述相同的偏移编码，更多信息请参考 `:h vim.lsp.start`
}

具体操作请参考你的插件文档。

copilot.lua 快速上手指南

copilot.lua 是 github/copilot.vim 的纯 Lua 重构版本，专为 Neovim 设计。相比原版，它性能更高、发热更低，且能更好地与现代插件（如 cmp）集成，避免幽灵文本冲突。

环境准备

在开始之前，请确保您的系统满足以下要求：

• Neovim: 版本 0.11.0 或更高。
• Curl: 用于网络请求。
• Node.js: 若使用默认的 Node.js LSP 版本，需安装 v22 或更高版本。
  • 国内用户提示：建议使用 nvm 管理 Node 版本，或通过国内镜像源（如淘宝镜像）安装，以避免下载超时。

安装步骤

推荐使用插件管理器进行安装。以下以 lazy.nvim 和 packer.nvim 为例。

1. 配置插件管理器

使用 lazy.nvim:

{
  "zbirenbaum/copilot.lua",
  cmd = "Copilot",
  event = "InsertEnter", -- 建议在进入插入模式时懒加载
  dependencies = {
    "copilotlsp-nvim/copilot-lsp", -- 可选：用于 NES (Next Edit Suggestion) 功能
  },
  config = function()
    require("copilot").setup({})
  end,
}

使用 packer.nvim:

use {
  "zbirenbaum/copilot.lua",
  requires = {
    "copilotlsp-nvim/copilot-lsp", -- 可选
  },
  cmd = "Copilot",
  event = "InsertEnter",
  config = function()
    require("copilot").setup({})
  end,
}

2. 身份认证

安装完成后，重启 Neovim 并执行以下命令进行登录：

:Copilot auth

系统将引导您完成浏览器验证流程。验证成功后，凭证将自动保存在本地配置目录中。

• 切换账号/登出: :Copilot auth signout
• 查看认证信息: :Copilot auth info
• 自定义 GitHub 实例: 如果您使用的是企业版 GitHub，可在 setup 配置中设置 auth_provider_url = "https://your-corp.ghe.com/"。

基本使用

默认行为

安装并认证成功后，copilot.lua 即可工作：

• 幽灵文本建议：在插入模式下，代码建议会以灰色幽灵文本形式显示。
• 接受建议：默认按键为 <M-l> (Alt + l)。
• 切换建议：使用 <M-]> (下一个) 或 <M-[> (上一个)。
• 拒绝建议：继续正常打字或按 <C-]> dismiss。

面板模式 (Panel Mode)

如果您更喜欢在侧边栏预览多个建议方案，可以使用面板模式：

1. 打开面板：

   :Copilot panel
   

2. 在面板中使用快捷键：
   • ]] / [[ : 跳转下一条/上一条建议
   • <CR> : 接受当前选中的建议
   • gr : 刷新建议

基础配置示例

您可以将以下配置放入 init.lua 或专门的配置文件中，以自定义按键映射和行为：

require("copilot").setup({
  suggestion = {
    enabled = true,
    auto_trigger = false, -- 设为 true 可进入插入模式即自动触发
    keymap = {
      accept = "<M-l>",       -- 接受整行建议
      accept_word = false,    -- 接受单词 (可自定义按键)
      accept_line = false,    -- 接受单行 (可自定义按键)
      next = "<M-]>",         -- 下一条建议
      prev = "<M-[>",         -- 上一条建议
      dismiss = "<C-]>",      -- 关闭建议
    },
  },
  panel = {
    enabled = true,
    keymap = {
      jump_prev = "[[",
      jump_next = "]]",
      accept = "<CR>",
      open = "<M-CR>"
    },
  },
  -- 自定义高亮组 (可选)
  -- 建议在 colorscheme 加载后设置
})

与其他补全插件集成 (如 nvim-cmp)

为了避免 Copilot 的幽灵文本与 cmp 的弹出菜单冲突，可以添加以下自动命令：

cmp.event:on("menu_opened", function()
  vim.b.copilot_suggestion_hidden = true
end)

cmp.event:on("menu_closed", function()
  vim.b.copilot_suggestion_hidden = false
end)

现在您已经完成了 copilot.lua 的基础配置，可以开始享受高效的 AI 编码辅助了。