Claude Code 缓存清理完整指南

Claude Code 在使用过程中会在本地生成大量缓存、日志和临时文件。定期清理这些文件可以释放磁盘空间并解决一些常见问题。本文提供跨平台的清理方法和最佳实践。

理解 Claude Code 的文件结构

在开始清理之前，了解 Claude Code 的文件结构非常重要。主要包含以下目录和文件：

~/.claude/ - 主配置目录，包含所有用户数据
~/.claude.json - 全局配置文件
~/.claude/projects/ - 项目会话记录
~/.claude/shell-snapshots/ - 命令行快照
~/.claude/statsig/ - 统计数据
~/.claude/todos/ - 任务管理数据
~/.claude/skills/ - 自定义技能（需要特别保护）

清理前的准备工作

在执行任何清理操作前，强烈建议进行以下准备工作：

备份重要配置：特别是自定义技能和钩子脚本，这些可能包含你精心配置的工作流程。

记录当前设置：截图或记录重要的配置项，以便在需要时恢复。

确认 Claude Code 已关闭：确保没有正在运行的 Claude Code 进程。

Windows 系统清理方法

在 Windows 系统中，清理过程相对简单直接。

使用文件资源管理器导航到用户目录，找到 .claude 目录和 .claude.json 文件。通过重命名的方式备份这些文件，例如将 .claude 目录改为 .claude-20251014，将 .claude.json 文件改为 .claude.json-20251014。

这种方法的优势是操作简单，且保留了原始文件作为备份。如果发现问题，可以随时恢复原始名称。

macOS 系统清理方法

macOS 系统提供了更灵活的命令行操作方式。根据清理需求的不同，可以选择温和清理或彻底重置。

温和清理方案

温和清理主要针对会话记录和临时文件，保留核心配置和技能设置。创建一个名为 ccclear.sh 的脚本：

#!/bin/bash

# 移动本地记录（所有项目会话记录会被移动）：
mv ~/.claude/projects ~/.claude/projects-$(date "+%Y%m%d%H%M%S")
mv ~/.claude/shell-snapshots ~/.claude/shell-snapshots-$(date "+%Y%m%d%H%M%S")
mv ~/.claude/statsig ~/.claude/statsig-$(date "+%Y%m%d%H%M%S")
mv ~/.claude/todos ~/.claude/todos-$(date "+%Y%m%d%H%M%S")

ls ~/.claude

这种方法适合定期维护，能够清理占用空间较大的会话数据，同时保留你的技能配置和个人设置。

彻底重置方案

当遇到顽固问题或需要完全重新开始时，可以使用彻底重置方法。创建 ccmoveconfig.sh 脚本：

#!/bin/bash

# 彻底版本，移动所有配置和记录：
mv ~/.claude ~/.claude-$(date "+%Y%m%d%H%M%S")
mv ~/.claude.json ~/.claude.json-$(date "+%Y%m%d%H%M%S")

ls ~/.claude

这种方法会移动所有配置文件，包括技能、钩子脚本和个性化设置。使用前请确保已备份重要数据。

保护技能配置的最佳实践

对于像 astro-markdown-optimizer 这样的自定义技能，需要特别小心处理。

单独备份技能目录：在执行任何清理操作前，先将 .claude/skills 目录复制到安全位置。

使用温和清理优先：除非确实需要，否则优先选择温和清理方案，避免影响技能配置。

清理后验证技能：清理完成后，重新启动 Claude Code 并验证技能是否正常工作。

清理后的配置恢复

如果使用了彻底重置方法，需要重新配置 Claude Code 并恢复技能设置。

重新初始化配置：启动 Claude Code，按照向导完成基本配置。

恢复技能文件：将之前备份的技能目录复制回新的 .claude/skills 目录。

验证钩子脚本：检查 .claude/hooks 目录中的脚本是否正常工作。

测试技能功能：使用已知的关键词测试技能是否能正常触发。

常见问题及解决方案

清理过程中可能遇到一些常见问题。

技能无法加载：这通常是因为技能文件路径或权限问题。检查技能文件是否存在于正确位置，并确保文件权限设置正确。

配置丢失：如果在清理前没有备份重要配置，可能需要重新设置。建议定期备份 .claude 目录。

性能未改善：如果清理后性能改善不明显，可能需要检查其他影响因素，如系统资源占用或网络连接。

维护建议

建立良好的维护习惯可以避免很多问题。

定期温和清理：每月执行一次温和清理，避免缓存文件积累过多。

重要变更前备份：在进行重大配置更改或系统升级前，备份整个 .claude 目录。

监控磁盘使用：定期检查 .claude 目录的大小，及时清理不必要的文件。

文档化配置：记录重要的配置项和自定义设置，便于在需要时恢复。

通过遵循这些指导原则，你可以安全有效地管理 Claude Code 的缓存和配置，确保工具始终保持最佳性能状态。

相关文章