CFAPI问题排查：CfDehydratePlaceholder执行卡住 无法接收脱水回调

1. 同步根注册未开启脱水支持 #

注册同步根时必须显式添加 CF_REGISTER_ROOT_SUPPORTS_DEHYDRATION 标志，否则系统不会向你的应用推送任何脱水相关回调，也不会允许文件进入脱水流程。Cloud Mirror官方示例默认未开启该配置，需要手动修改注册逻辑。

2. 单个占位文件未开启脱水权限 #

创建占位文件时，需要在CF_PLACEHOLDER_CREATE_INFO的Flags字段添加CF_PLACEHOLDER_FLAG_ALLOW_DEHYDRATION标志，未添加该标志的文件即使根目录开启了脱水支持，也无法执行脱水操作。

3. 回调类型注册不完整 #

注册回调函数时必须显式声明监听以下两类回调：

• CF_CALLBACK_TYPE_NOTIFY_DEHYDRATE：脱水前的通知回调，你需要在该回调中校验文件是否允许脱水，返回STATUS_SUCCESS即确认允许脱水
• CF_CALLBACK_TYPE_NOTIFY_DEHYDRATE_COMPLETION：脱水完成后的结果通知回调

4. 文件存在未同步的本地修改 #

系统默认不允许存在脏数据的文件脱水，你需要先完成以下前置操作：

• 确保文件的所有本地修改已经上传到云端
• 调用CfSetInSyncState将文件状态设置为CF_IN_SYNC_STATE_IN_SYNC，注意该操作必须使用通过CfOpenFileWithOplock打开的有效文件句柄执行，普通文件句柄调用可能不生效

5. 手动调用CfDehydratePlaceholder的参数错误 #

手动触发脱水时需要遵循正确的调用流程：

1. 调用CfOpenFileWithOplock打开目标占位文件，请求至少READ_ATTRIBUTES和WRITE_ATTRIBUTES权限
2. 完成文件同步状态校验，调用CfSetInSyncState标记文件为已同步
3. 调用CfDehydratePlaceholder，文件偏移和长度参数按实际需求填写，无特殊需求时Flags字段传CF_DEHYDRATE_FLAG_NONE即可
4. 如果需要强制脱水有未提交修改的文件，可以添加CF_DEHYDRATE_FLAG_ALLOW_DEHYDRATE_WHEN_MODIFIED标志，但该操作会丢弃本地未同步的修改

额外排查建议 #

如果以上配置都正确仍存在问题，可先执行cfregister /unregister [你的同步根路径]注销残留的同步根注册信息，清理后重新注册再测试，避免旧配置残留导致的异常。

内容的提问来源于stack exchange，提问作者Trafo