必须安装 alefragnani.bookmarks 插件，确认作者为 Alessandro Fragnani，命令 Bookmarks: Toggle 可执行且启用 "bookmarks.persistAll": true 才能持久化书签。
Bookmarks 插件不是 VSCode 内置功能，必须手动安装 alefragnani 版本才能用；装错版本（比如作者名拼错、或用了旧版 Code Bookmarks）会导致快捷键无响应、书签不跨文件、甚至列表为空。
怎么确认装对了插件
打开扩展面板（Ctrl+Shift+X），搜索 Bookmarks，只认准作者是 Alessandro Fragnani（不是 Alex Dubé、Aleksey Leshko 或其他变体）。安装后别急着按快捷键——先打开命令面板（Ctrl+Shift+P），输入 Bookmarks: Toggle，看是否能执行并触发行号旁的标记。如果命令不存在，说明插件根本没加载，重装并重启 VSCode。
- 插件 ID 是
alefragnani.bookmarks，可在扩展详情页 URL 末尾核对 - 安装后无需重启，但快捷键绑定有时需手动触发一次命令才生效
- 若已装其他同名插件（如
Code Bookmarks），必须先禁用或卸载，否则命令冲突
Ctrl+Alt+K 按了没反应？先查这三处
默认快捷键 Ctrl+Alt+K 在 Windows/Linux 上极易被劫持：输入法（尤其是中文输入法）、笔记本 Fn 键、系统级快捷键（如 Windows 的“切换输入语言”）都会吃掉这个组合。不是插件坏了，是键盘信号根本没传到 VSCode。
- 临时关闭所有输入法，再试
Ctrl+Alt+K - 检查 VSCode 键位设置：打开
keybindings.json，搜索bookmarks.toggle，确认该条目存在且未被when条件禁用 - 在命令面板中手动执行
Bookmarks: Toggle，验证功能本身正常——如果命令能运行，就是快捷键问题，不是插件问题
书签跨文件失效或重启就消失
默认情况下，alefragnani.bookmarks 只把书签存进内存，关掉窗口或重启 VSCode 就清空。它不会自动写入工作区配置，更不会同步到 Settings Sync。
- 要持久化，必须在工作区设置（
.vscode/settings.json）里加一行："bookmarks.persistAll": true - 启用后，数据会落地为
.vscode/bookmarks.json，Git 可追踪，多人协作时也能共享书签结构 - 多根工作区（multi-root workspace）下，每个文件夹独立保存书签，不能跨根访问——这是设计限制，不是 bug
Bookmarks: List 显示空或跳转失败
Bookmarks: List（快捷键 Ctrl+Alt+L）列出的是当前工作区所有书签，但它的行为依赖两个隐性条件：文件必须在工作区目录内，且路径不能含非法字符（如空格、中文未编码、符号链接断裂）。
- 如果某文件是通过拖拽外部路径打开的（不在当前工作区目录树里），它设的书签不会出现在列表中
- 跳转时 VSCode 会尝试打开目标文件，若该文件已被删除、重命名或权限不足，面板里仍显示该条目，但点击后报错
Unable to open 'xxx': File not found. - 模糊搜索只匹配文件名和代码前 30 字符，注释太短或关键词在第 31 字符之后就搜不到
真正容易被忽略的是：Bookmarks 不感知代码语义。你在函数里打了个书签，大纲视图（Outline）点进去不会高亮它；折叠代码块后，书签图标照样显示在行号旁，但那行可能已经被收起来了——它只记行号，不记逻辑上下文。
