1. Ubuntu 上 C++ 插件装了却没提示，先别急着重装
你在 Ubuntu 上打开 VS Code，左边扩展栏里明明显示 C/C++ 插件已经安装，状态也是「已启用」，可一敲printf或者#include <stdio.h>，补全列表空空如也，连个灰字提示都没有。这种「插件在、提示没」的情况，我遇到过不止一次，绝大多数时候不是插件坏了，而是 IntelliSense 引擎没找到头文件，或者它压根没跑在你以为的那台机器上。
先把结论摆出来：VS Code 的 C/C++ 插件本身只是个「壳」，真正干活的是它背后的 IntelliSense 引擎（基于语言服务器）。这个引擎需要知道三件事——你的编译器在哪、系统头文件在哪、你的项目头文件在哪。只要其中任何一环缺失，它就会静默失败，界面上不报错，只是不给你提示，看起来就像插件没生效。
这篇排查清单覆盖两种最常见的场景：一是在 Ubuntu 本地直接开 VS Code 写 C++，二是用 Remote-SSH 连到远程 Ubuntu 上写代码。这两种场景下「没提示」的根因往往不同，本地多半是includePath没配，远程则经常是插件装错了地方——你装在了本地，但代码和编译器都在远端。下面按c_cpp_properties.json、compile_commands.json、includePath、IntelliSense 引擎状态这几条线，逐项定位。
适合谁看：刚在 Ubuntu 上配好 VS Code 想写 C/C++ 的新手，以及用 Remote-SSH 连服务器写代码、被「插件装了没反应」卡住的开发者。跟着做，你能拿到可复制的配置片段和明确的验证动作，而不是靠反复重装碰运气。
2. 先搞清楚 IntelliSense 引擎到底跑在哪台机器上
排查之前必须先确认一件事：你的 C/C++ 插件是装在本地还是远端。这一步在 Remote-SSH 场景下尤其关键，也是最多人踩的坑。
VS Code 的 Remote-SSH 架构是这样的：本地 VS Code 只是一个「客户端界面」，真正的文件系统、终端、扩展宿主（Extension Host）都跑在远端 Ubuntu 上。所以 C/C++ 插件必须装在远端，IntelliSense 引擎也在远端运行，它读的是远端 Ubuntu 的/usr/include、/usr/lib/gcc这些目录。如果你只在本地装了插件，远端没装，那远端代码自然没有任何提示。
怎么确认？连上 Remote-SSH 后，打开扩展面板，看 C/C++ 插件那一栏。如果显示的是「在 SSH: xxx 上安装」按钮，说明远端还没装；如果显示「已启用」并且下面有小字标注运行位置是 SSH 主机，那才是装对了。本地窗口和远程窗口的扩展是分开管理的，这一点和普通本地开发完全不同。
确认引擎位置之后，再看引擎状态。VS Code 底部状态栏右下角会有一个 C/C++ 的小图标，鼠标悬停能看到 IntelliSense 的状态。如果显示「Parsing」很久不结束，或者显示「IntelliSense: 未配置」，那就是配置没到位。你也可以打开命令面板（Ctrl+Shift+P），运行C/C++: Log Diagnostics，它会弹出一个输出面板，列出当前引擎识别的编译器路径、includePath、defines 等，一眼就能看出它「以为」的头文件目录对不对。
还有一个更直接的验证动作：打开输出面板（Ctrl+Shift+U），右上角下拉选「C/C++」，然后随便打开一个.cpp文件，敲一个#include <，看日志里有没有报「cannot find include file」或者「IntelliSense engine failed」。日志是排查的第一手证据，比盯着补全列表猜要靠谱得多。
这里要提醒一句：如果你在远端 Ubuntu 上还没装编译器，IntelliSense 连「猜」的基准都没有。先在远端终端跑一下gcc --version和g++ --version，确认编译器存在。没有的话sudo apt install build-essential装上，这是后面所有配置的前提。
3. 可复制的 c_cpp_properties.json 与 compile_commands.json 配置
配置是解决「没提示」的核心。C/C++ 插件读取配置有两个来源：一是手动写的c_cpp_properties.json，二是编译数据库compile_commands.json。前者适合小项目或单文件，后者适合有构建系统（CMake、Make）的项目，优先级更高、更准确。
3.1 手动配置 c_cpp_properties.json
这个文件放在工作区的.vscode/目录下，或者放在用户全局配置目录~/.config/Code/User/下作为默认。最省事的做法是让 gcc 自己把系统头文件目录打印出来，直接写进配置。在 Ubuntu 终端执行：
mkdir -p ~/.config/Code/User echo "{ \"version\": 4, \"configurations\": [ { \"name\": \"Linux-default\", \"includePath\": [ \"\${workspaceFolder}/**\", \"$(gcc -xc -E -v /dev/null 2>&1 | sed -n '/^#include.*search starts here:/,/^End of search list./p' | grep ' /usr' | tr -d '\n' | sed 's/ /\", \"/g')\" ], \"defines\": [], \"compilerPath\": \"/usr/bin/gcc\", \"cStandard\": \"c11\", \"cppStandard\": \"c++17\", \"intelliSenseMode\": \"linux-gcc-x64\" } ] }" > ~/.config/Code/User/c_cpp_properties.json这段命令的关键在于中间那串gcc -xc -E -v /dev/null，它让 gcc 把默认的头文件搜索路径全部打印出来，再用sed和grep过滤出/usr开头的目录，拼成 JSON 数组。这样includePath里就自动包含了/usr/include、/usr/include/c++/11、/usr/include/x86_64-linux-gnu等真实路径，不用你手动一个个找。
写完之后，如果你是在 Remote-SSH 里，注意这个路径是远端 Ubuntu 的~/.config/Code/User/，不是本地的。配置改完要重新加载窗口（命令面板运行Developer: Reload Window）才生效。
3.2 用 compile_commands.json 让配置自动化
如果你的项目用 CMake 构建，更推荐生成compile_commands.json，让插件直接读编译命令，includePath 和 defines 全都自动对齐，比手写准确得多。CMake 项目在配置时加上：
cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ln -s build/compile_commands.json compile_commands.jsonCMAKE_EXPORT_COMPILE_COMMANDS=ON会生成编译数据库，软链接放到项目根目录后，C/C++ 插件会自动识别。然后在c_cpp_properties.json里把compileCommands指过去：
{ "version": 4, "configurations": [ { "name": "Linux", "compileCommands": "${workspaceFolder}/compile_commands.json", "compilerPath": "/usr/bin/g++", "cppStandard": "c++17", "intelliSenseMode": "linux-gcc-x64" } ] }用 Makefile 的项目可以用bear生成：sudo apt install bear，然后bear -- make，同样会产出compile_commands.json。有了它，插件不再靠猜，补全和跳转都会准很多。
3.3 三件套对照表
无论本地还是远程，配置的核心三件套是 Base URL、Key、Model ID 这套思路在 AI 工具接入里通用，但 C++ 插件这里对应的是编译器路径、includePath、标准版本。对照如下：
| 配置项 | 作用 | 典型值 |
|---|---|---|
| compilerPath | 指定编译器，引擎据此推断系统头文件 | /usr/bin/gcc 或 /usr/bin/g++ |
| includePath | 头文件搜索目录 | ${workspaceFolder}/** 加系统路径 |
| cppStandard | C++ 标准版本 | c++17 / c++20 |
| intelliSenseMode | 引擎模式，需匹配平台 | linux-gcc-x64 |
配置写好后，重新加载窗口，再打开.cpp文件，等状态栏的 C/C++ 图标从「Parsing」变成正常状态，补全应该就回来了。
4. 验证请求：从输出面板日志到一次成功的补全
配置改完不代表就好了，得验证。我习惯按这个顺序走一遍，每一步都有明确的观察点。
第一步，打开输出面板。Ctrl+Shift+U，右上角下拉选「C/C++」。然后打开一个.cpp文件，敲#include <stdio.h>。正常情况日志里会显示引擎正在解析、加载了哪些头文件路径。如果看到cannot find include file "stdio.h"，说明 includePath 还是不对，回到第 3 节检查路径是否真的存在——在远端终端ls /usr/include/stdio.h确认一下。
第二步，触发一次补全。在main函数里敲printf，正常应该弹出补全列表，函数签名和参数提示都有。如果没弹，先按Ctrl+Space手动触发一次。手动触发能弹出来，说明引擎是活的，只是自动触发被某些设置关了，检查editor.quickSuggestions是否为 true。
第三步，看索引是否完成。大项目首次打开时，引擎要建索引，状态栏会显示进度。索引没完成之前补全可能不全，等它跑完再试。你可以在命令面板运行C/C++: Rescan Workspace强制重新扫描。
第四步，验证跳转。把光标放在printf上按F12，能跳到/usr/include/stdio.h的声明处，说明头文件路径完全正确。跳转和补全用的是同一套索引，跳转成功基本就稳了。
如果你在 Remote-SSH 场景，还要确认一件事：远端 Ubuntu 上是否装了 C/C++ 插件。前面说过，本地装了不算数。在远程窗口的扩展面板里搜 C/C++，如果显示「Install in SSH: xxx」，点它装到远端。装完重新加载远程窗口，再走一遍上面的验证。
实测下来，大部分「插件装了没提示」的问题，走到第三步就能定位——要么是 includePath 缺系统路径，要么是插件装在了本地而代码在远端。真正需要重装插件的情况极少。
5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth
排查过程中你会遇到一些报错，有些和 C++ 插件直接相关，有些是环境或网络层面的。逐个说清楚。
「cannot find include file」：最典型。引擎找不到头文件，根因是 includePath 没包含系统目录。解决就是第 3 节那段 gcc 打印路径的命令，或者用 compile_commands.json。注意 Remote-SSH 下路径必须是远端的，别把本地的/usr/include写进去。
「IntelliSense engine failed」或引擎反复重启：多半是插件版本和 VS Code 版本不匹配，或者远端内存不足导致语言服务器被杀。先看输出面板的详细堆栈，再考虑更新插件。远端内存小的话，可以在设置里调低C_Cpp.intelliSenseMemoryLimit。
「local proxy failed」：这个报错通常出现在 VS Code 尝试联网下载组件或同步设置时。如果你在受限网络环境，插件的一些在线功能会失败，但本地补全不依赖网络，可以忽略。要彻底消掉，检查 VS Code 的代理设置http.proxy，把它清空或指向可用地址。
「reading choices」相关报错：这类报错常见于插件读取配置或补全数据时 JSON 解析失败。检查c_cpp_properties.json是否是合法 JSON——多一个逗号、少一个引号都会导致整个配置被忽略，引擎退回默认状态，表现就是没提示。用python -m json.tool c_cpp_properties.json验证一下格式。
「OAuth」或登录相关提示：如果你在用某些需要账号的 AI 编程辅助功能，可能会遇到 OAuth 回调失败。这类问题和 C++ 插件本身无关，属于辅助工具的接入问题。排查思路是确认回调地址、端口是否被占用，以及网络是否可达。如果你在接入类似 TaoToken 这样的模型服务做代码辅助，Base URL、Key、Model ID 三件套要填对，缺一个都会认证失败。模型对话入口在 https://taotoken.net/api ，接入文档在 https://taotoken.net/api-keys 可以查到具体的 Key 管理和调用方式。
Remote-SSH 连不上导致插件失效：如果 SSH 连接本身断了，远端扩展宿主也就没了，补全自然消失。先确认 SSH 连接稳定，再排查插件。可以在远端终端ps aux | grep cpptools看语言服务器进程在不在。
排查的核心逻辑是：先确认引擎跑在哪、活没活，再看配置对不对，最后才怀疑插件本身。顺序反了会浪费很多时间。
6. 把配置固化下来，下次换机器直接复用
排查完一次，最好把有效的配置固化，避免下次换机器或重装系统再来一遍。我的做法是把~/.config/Code/User/c_cpp_properties.json这份全局配置备份到 dotfiles 仓库，新机器上一条命令恢复。项目级的.vscode/c_cpp_properties.json跟着项目走，用 compile_commands.json 的项目记得把生成步骤写进 README 或 CMake 配置里。
如果你经常用 Remote-SSH 连多台 Ubuntu 服务器，建议在每台远端都装好 C/C++ 插件和 build-essential，配置用同一份模板。VS Code 的 Settings Sync 可以同步本地设置，但远端扩展和远端配置需要单独处理，别指望它自动同步过去。
对于需要 AI 辅助补全和代码解释的场景，可以把模型服务接进来配合使用。长期做 C++ 编码和 Agent 类任务的话，Coding Plan 在 https://taotoken.net/coding-plan 有对应的方案，模型对话可以直接在 https://taotoken.net/api 试。控制台在 https://taotoken.net/console ，API Key 管理在 https://taotoken.net/api-keys 。Claude Code 相关的接入参考 https://taotoken.net/claude-code 。这些工具和 C++ 插件是互补关系，插件负责语言层面的补全跳转，模型服务负责更高层的代码理解和生成，配置思路都是把地址、密钥、模型标识填对。
最后留一个实用习惯：每次改完c_cpp_properties.json，先跑C/C++: Log Diagnostics确认引擎读到的路径符合预期，再打开代码验证补全。这个动作花不了十秒，能省掉大量「改了没生效」的困惑。配置这东西，看得见才算数。
