CopilotChat.nvim版本升级与迁移指南：从v3.x到v4.x的重大变化

CopilotChat.nvim是一款让你在Neovim中与GitHub Copilot进行聊天的插件。本指南将帮助你顺利从v3.x版本升级到v4.x版本，了解新特性和重要变更，轻松完成迁移过程。## 🌟 升级前的准备工作在开始升级之前，请确保你的系统满足以下要求：- 已安装 [plenary.nvim](https://github.com/nvim-lua/plenary.nvi

巫清焘

1025人浏览 · 2026-03-22 02:00:43

巫清焘 · 2026-03-22 02:00:43 发布

CopilotChat.nvim版本升级与迁移指南：从v3.x到v4.x的重大变化

【免费下载链接】CopilotChat.nvim Chat with GitHub Copilot in Neovim 项目地址: https://gitcode.com/gh_mirrors/co/CopilotChat.nvim

CopilotChat.nvim是一款让你在Neovim中与GitHub Copilot进行聊天的插件。本指南将帮助你顺利从v3.x版本升级到v4.x版本，了解新特性和重要变更，轻松完成迁移过程。

🌟 升级前的准备工作

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

已安装 plenary.nvim 插件
已安装 copilot.vim 或 copilot.lua 插件
系统中已安装 curl（Neovim通常会默认包含）

升级前请执行以下命令确保Copilot已正确授权：

:Copilot setup

或

:Copilot auth

同时，运行以下命令清理旧的Python命令：

:UpdateRemotePlugins

🔧 配置变更详解

v4.x版本对配置参数进行了优化和调整，以下是主要变更：

移除的参数

disable_extra_info: 已移除，现在可以通过按键绑定按需显示当前选择内容
hide_system_prompt: 已移除，现在可以通过按键绑定按需显示当前系统提示
language: 已移除，现在作为selection.filetype的一部分

新增的配置选项

v4.x版本引入了更多灵活的配置选项，主要集中在 lua/CopilotChat/config.lua 文件中：

window.layout: 控制聊天窗口布局，支持 'vertical'、'horizontal'、'float'、'replace' 或自定义函数
diff: 控制差异显示格式，支持 'block' 或 'unified'
selection: 选择源，支持 'visual' 或 'unnamed'
auto_fold: 自动折叠非助手消息（需配合 show_folds 使用）

⌨️ 命令变更指南

v4.x版本对命令系统进行了重构，以下是主要变更：

已移除的命令

CopilotChatBuffer: 已移除，现在可通过 select.buffer 选择器实现
CopilotChatInPlace: 已移除，功能已合并到默认聊天界面，浮动窗口可通过 window.layout = 'float' 实现

重命名的命令

CopilotChatVsplitToggle 已重命名为 CopilotChatToggle

行为变更的命令

CopilotChat 现在的行为类似于之前的 CopilotChatVisual
无名寄存器选择现在可通过 select.unnamed 选择器实现

🛠️ API变更与迁移

v4.x版本对API进行了重大改进，以下是主要变更：

代码操作API变更

CopilotChat.code_actions.show_help_actions 已重构为：

local actions = require("CopilotChat.actions")
require("CopilotChat.integrations.telescope").pick(actions.help_actions())

CopilotChat.code_actions.show_prompt_actions 已重构为：

local actions = require("CopilotChat.actions")
local select = require("CopilotChat.select")
require("CopilotChat.integrations.telescope").pick(actions.prompt_actions({
    selection = select.visual,
}))

函数系统重构

v4.x版本引入了全新的函数系统，相关实现可在 lua/CopilotChat/functions.lua 文件中查看。新系统支持：

函数参数自动解析与验证
URI模板参数替换
基于JSON Schema的输入解析
交互式参数输入

🔄 如何恢复旧版行为

如果你习惯了v3.x版本的操作方式，可以通过以下配置恢复旧版行为：

local chat = require('CopilotChat')
local select = require('CopilotChat.select')

chat.setup {
    -- 恢复CopilotChat默认使用无名寄存器的行为
    selection = select.unnamed,
    -- 恢复使用##作为标题前缀的格式
    question_header = '## User ',
    answer_header = '## Copilot ',
    error_header = '## Error ',
}

-- 恢复CopilotChatVisual命令
vim.api.nvim_create_user_command('CopilotChatVisual', function(args)
    chat.ask(args.args, { selection = select.visual })
end, { nargs = '*', range = true })

-- 恢复CopilotChatInPlace命令（类似）
vim.api.nvim_create_user_command('CopilotChatInPlace', function(args)
    chat.ask(args.args, { selection = select.visual, window = { layout = 'float' } })
end, { nargs = '*', range = true })

-- 恢复CopilotChatBuffer命令
vim.api.nvim_create_user_command('CopilotChatBuffer', function(args)
    chat.ask(args.args, { selection = select.buffer })
end, { nargs = '*', range = true })

-- 恢复CopilotChatVsplitToggle命令
vim.api.nvim_create_user_command('CopilotChatVsplitToggle', chat.toggle, {})

更多配置示例可参考 @jellydn的配置。