ctxsync 核心命令详解:掌握 push 文件同步的 10 个关键细节

ctxsync 核心命令详解:掌握 push 文件同步的 10 个关键细节

【免费下载链接】ctxsyncctxsync is a Python tool that automates the synchronization of local files with Claude.ai Projects项目地址: https://gitcode.com/gh_mirrors/cl/ctxsync

ctxsync 是一款用 Python 编写的开源工具，它能自动化地把本地文件同步到 Claude.ai Projects，而ctxsync push 文件同步正是其中最核心、最高频使用的命令。无论你是想把手头的代码库一键推送到 Claude 项目，还是希望本地改动实时反映到云端，理解 push 命令的底层逻辑都能帮你少踩坑、用得更顺手。本文面向新手，用最直白的方式拆解 push 文件同步背后的 10 个关键细节，让你从"会敲命令"进阶到"真正懂同步"。

一、ctxsync push 文件同步是什么？

简单说，claudesync push会把当前本地项目中符合条件的文件，逐个上传到你绑定的 Claude.ai 项目里。它并不是盲目地把整个文件夹一股脑传上去，而是经过"扫描 → 过滤 → 校验 → 上传"的完整流程。这一流程主要由 main.py 中的 push 命令入口触发，同步核心逻辑则集中在 syncmanager.py 的 SyncManager 类中。

二、push 前的必备准备工作

在运行 push 之前，请务必确认以下三步已经完成，否则命令会直接报错退出：

1. 登录认证：执行claudesync auth login，获得有效的 session key。
2. 绑定组织：执行claudesync organization set，选择目标组织。
3. 初始化项目：执行claudesync project create或claudesync project set，在项目目录生成.claudesync配置目录。

💡 小提示：项目配置保存在.claudesync/config.local.json中，push 会向上逐级查找该目录，找不到时会提示你先初始化。

三、掌握 push 文件同步的 10 个关键细节

细节 1：先跑 --dryrun 试运行，避免误操作

这是最实用的细节之一！claudesync push --dryrun只会列出将要发送的文件，并不会真正上传。新手第一次使用时强烈建议先跑一遍试运行，确认同步范围符合预期再正式执行。源码中 dryrun 分支会打印Would send file: xxx并直接返回，见 main.py 中的 push 函数。

claudesync push --dryrun

细节 2：push 默认是单向上传，从本地到云端

push 命令的本质是"本地 → 云端"的单向传输。默认配置two_way_sync为 false，意味着云端的改动不会回传到本地。如果你需要双向同步，可以用claudesync config set two_way_sync true开启。注意：双向模式下，云端文件也会覆盖本地同名文件，使用时请谨慎。

细节 3：prune_remote_files 决定"多余文件"的去留

默认配置prune_remote_files为 true，也就是说：本地已经删除的文件，也会从 Claude.ai 项目中删除，保证云端与本地完全一致。如果你不希望云端文件被清理，可以执行：

claudesync config set prune_remote_files false

这一开关在 base_config_manager.py 的默认配置中定义，判断逻辑位于 SyncManager 的prune_remote_files方法。

细节 4：单个文件默认上限 32KB，超出会被跳过

为了适配 Claude.ai 的接口限制，默认max_file_size为 32KB（32 × 1024 字节）。超过该大小的文件会被静默跳过。如果你确实需要同步大文件，可以调大这个值：

claudesync config set max_file_size 65536

该过滤逻辑在 utils.py 的should_process_file函数中实现。

细节 5：.gitignore 与 .claudeignore 双重过滤

push 会自动读取项目根目录的.gitignore和.claudeignore文件，被匹配到的文件不会上传。这相当于给文件同步加上了"白名单/黑名单"机制——不想让 Claude 看到的密钥、日志、构建产物，都可以写进.claudeignore。另外，.git、.svn、.claudesync等目录默认就会被排除。

细节 6：--category 参数实现按分类精准同步

如果你只想同步源码、测试代码或构建配置，可以用--category指定分类。项目内置了all_files、all_source_code、test_code、build_config等多个分类，例如：

claudesync push --category test_code

分类的匹配规则在 base_config_manager.py 的file_categories配置中定义，你也可以通过claudesync category相关命令自定义。

细节 7：--uberproject 合并子模块一起同步

对于包含多个子模块（如多 Maven 模块、多 npm 包）的项目，默认 push 只会同步主项目，子模块会各自映射到独立的 Claude 项目。加上--uberproject参数后，子模块文件也会一并进入父项目，实现"超级项目"的合并同步。判断子模块的依据是 pom.xml、package.json、go.mod 等特征文件。

细节 8：MD5 校验决定"改没改"，不是每次都全量上传

push 不是无脑重复上传！SyncManager 会计算每个本地文件的 MD5 哈希，并与云端文件的哈希比对：哈希相同则跳过，不同才删除重建。这意味着你修改过的文件才会真正触发上传，大幅节省时间和接口调用。相关实现见 utils.py 的compute_md5_hash函数。

细节 9：遇到 403 错误会自动重试，最多 3 次

Claude.ai 接口偶尔会返回 403（可能是限流或临时故障）。push 内置了retry_on_403装饰器，遇到 403 会等待 1 秒后重试，最多重试 3 次，降低同步失败的概率。当然，如果连续失败，说明会话可能已过期，重新执行claudesync auth login即可恢复。

细节 10：upload_delay 控制上传节奏，避免触发限流

每次上传后，工具会默认等待 0.5 秒（upload_delay）再继续下一个文件，这是为了给接口留出喘息空间。如果你上传频繁报错，可以适当调大这个值：

claudesync config set upload_delay 1.5

另外，push 过程中会以进度条（tqdm）展示每个文件的上传状态，让你对同步进度一目了然。

四、push 文件同步的常见问题速查

五、总结

ctxsync push 文件同步看似简单，背后却藏着过滤、校验、重试、限流保护等一整套精心设计的机制。掌握了上面这 10 个关键细节，你就能根据自己的项目类型灵活配置，让本地代码与 Claude.ai 项目始终保持同步，把精力真正集中在开发本身。如果想深入了解实现源码，可以查看 syncmanager.py 和 utils.py，源码中的注释和默认配置会给你更多启发。

⚠️ 免责声明：ctxsync 是独立的开源项目，与 Anthropic 或 Claude.ai 无隶属关系，请在使用前了解并遵守相关服务条款。

【免费下载链接】ctxsyncctxsync is a Python tool that automates the synchronization of local files with Claude.ai Projects项目地址: https://gitcode.com/gh_mirrors/cl/ctxsync