常见问题
本指南涵盖了用户在使用 Sidian 时最常遇到的问题,并提供了逐步的解决方案以快速解决这些问题。
AI 功能无法正常工作
如果 Sidian 的 AI 功能没有响应或无法正常工作:
认证问题
AI 功能需要认证。
- 检查您是否已登录(在侧边栏查看账户状态)
- 尝试退出并重新登录
- 验证您的订阅是否有效
- 如果使用网页认证,请清除浏览器缓存
网络连接问题
云 AI 模型需要互联网连接。
- 对于云模型:检查您的互联网连接
- 对于本地模型:验证本地 AI 服务器(Ollama/LM Studio)是否正在运行
- 验证防火墙没有阻止 Sidian
- 如果使用云模型,尝试暂时禁用 VPN
- 检查公司代理是否造成干扰
配置问题
检查 AI 模型和提供商设置。
- 验证 API 密钥是否已正确配置
- 检查所选的 AI 模型是否可用
- 尝试切换到不同的 AI 提供商
- 将 AI 设置重置为默认值
MCP 服务器问题
关于模型上下文协议 (MCP) 服务器的问题:
服务器无法启动
- 检查 Node.js 是否已安装且可访问
- 验证服务器包是否已安装:
npm list -g
- 检查 MCP 配置文件的语法
- 查看服务器日志以获取具体的错误信息
- 尝试在终端中手动运行服务器命令
权限错误
- 确保 Sidian 对配置的目录具有读/写权限
- 检查项目文件夹的文件系统权限
- 如有必要,以管理员身份运行 Sidian (Windows)
- 验证 MCP 配置文件是否可读
服务器持续崩溃
- 将 MCP 服务器包更新到最新版本
- 检查是否存在冲突的 Node.js 版本
- 增加配置中的超时值
- 监控系统资源(CPU、内存)
- 检查服务器日志中的错误模式
性能问题
启动缓慢
- 禁用不必要的扩展
- 清除扩展缓存
- 减少打开文件的数量
- 检查工作区中是否有大文件
- 更新到最新的 Sidian 版本
内存占用过高
- 关闭未使用的文件和标签页
- 禁用占用大量内存的扩展
- 减少文件监视范围
- 清除搜索和符号缓存
- 定期重启 Sidian
CPU 占用过高
- 检查是否有失控的扩展
- 暂时禁用实时功能
- 降低 AI 建议的频率
- 关闭占用大量资源的终端
- 监控后台进程
文件和编辑器问题
文件无法加载
- 检查文件权限
- 验证文件路径是否正确
- 尝试刷新文件浏览器
- 检查文件是否被其他进程锁定
- 如果文件出现损坏,请重启 Sidian
自动保存不工作
- 在首选项中检查自动保存设置
- 验证文件的写入权限
- 确保有足够的磁盘空间
- 检查文件是否为只读
- 尝试手动保存以测试写入权限
搜索找不到文件
- 检查搜索的排除模式
- 验证文件扩展名是否未被过滤
- 尝试重建搜索索引
- 检查文件是否在 .gitignore 中
- 清除搜索缓存并重启
扩展问题
扩展无法安装
- 检查互联网连接
- 验证扩展的兼容性
- 清除扩展缓存
- 尝试从 VSIX 文件安装
- 检查可用的磁盘空间
扩展错误
- 在输出面板中检查扩展日志
- 禁用冲突的扩展
- 将扩展更新到最新版本
- 重置扩展设置 -向扩展作者报告问题
扩展无法加载
- 检查扩展是否已启用
- 验证扩展的依赖项
- 尝试重新加载窗口 (Ctrl+Shift+P → Reload Window)
- 检查扩展更新
- 重新安装扩展
Git 集成问题
Git 命令失败
- 验证 Git 是否已安装并在 PATH 中
- 检查仓库状态
- 确保 Git 配置正确
- 尝试在终端中执行 Git 操作
- 检查文件权限
合并冲突
- 使用内置的合并冲突解决工具
- 检查是否存在冲突的更改
- 确保所有更改都已暂存
- 尝试手动解决冲突
- 如果需要,使用外部合并工具
推送/拉取问题
- 检查远程仓库的访问权限
- 验证认证凭据
- 检查网络连接
- 尝试在终端中执行 Git 操作
- 将 Git 更新到最新版本
终端问题
终端无法打开
- 检查默认的 shell 配置
- 验证 shell 可执行文件是否存在
- 尝试不同的 shell(bash, zsh, PowerShell)
- 检查终端设置
- 重置终端配置
命令未找到
- 检查 PATH 环境变量
- 验证命令是否已安装
- 尝试使用可执行文件的完整路径
- 检查 shell 配置文件
- 重启终端会话
终端显示问题
- 检查终端字体设置
- 验证配色方案配置
- 尝试不同的终端渲染器
- 检查 Unicode 支持
- 重置终端外观设置
调试问题
调试器无法启动
- 检查调试配置
- 验证调试器是否已安装
- 检查 launch.json 语法
- 尝试不同的调试适配器
- 检查端口可用性
断点不生效
- 验证源映射 (source maps) 是否正确
- 检查代码是否被优化
- 尝试在启动后设置断点
- 检查调试器是否已附加
- 验证文件路径是否匹配
变量不显示
- 在调试控制台中检查错误
- 验证变量的作用域
- 尝试不同的调试适配器
- 检查表达式语法
- 重启调试会话
获取额外帮助
文档
- 查阅官方文档 docs.sidian.dev
- 查阅扩展文档
社区支持
- 加入 Sidian Discord 服务器
- 搜索 Stack Overflow
直接支持
- 联系 support@sidian.dev
- 附上错误日志和截图
- 描述重现问题的步骤
- 提及您的系统配置
诊断信息
报告问题时,请包括:
- Sidian 版本
- 操作系统
- 错误消息
- 重现问题的步骤
- 扩展列表
- 系统规格
大多数问题都可以通过遵循这些故障排除步骤来解决。如果问题仍然存在,请随时向社区或支持团队寻求帮助。