REDCap 数据导出实用指南

适用平台：陕西省重大疾病防控与大健康数据共享平台（REDCap 17.1） 读者：项目负责人、数据管理员、统计分析员 更新日期：2026-09-09

导出慢、文件过大、字段对不上，多半不是系统故障，而是一次拉取了过多字段、附件或全量历史。本指南说明网页导出与 API / R 的推荐做法，帮助您更快拿到可分析的数据集，同时保护受试者隐私与项目审计完整性。

---

1. 先分清三种「导出」

请先确认自己要的是哪一种，不要混用入口。

您想要的	在 REDCap 里点哪里	得到什么	是否用于统计分析
病例数据	应用程序 → 数据导出，或先做 报表 再导出	每条记录的字段值	是
变量说明	项目设置 → 数据字典，或导出时勾选 codebook	变量名、标签、选项编码	分析前对照用
操作轨迹	应用程序 → Logging	谁在何时改过数据、导出过数据	否（监查 / 稽查）

数据导出只读取项目记录，不会因为 Logging 里历史很长就变慢。Logging 导出才是日志查询；监查要轨迹时请加日期范围，不要一次导出全部历史。

---

2. 导出前核对清单

开始点击导出前，请逐项确认：

1. 权限：用户权限中「数据导出」至少为「去标识」或「完整数据集」。只有「无」则看不到导出菜单。
2. 数据访问组（DAG）：若您只属于某个中心，导出结果通常只含本中心记录。全库分析须由具有跨 DAG 权限的数据管理员操作。
3. 标识符字段：姓名、身份证、电话、详细住址等，分析集默认不要导出。需要完整数据时走伦理批准的路径，并由数据管理员操作。
4. 用途：统计分析用「原始值（raw）」；写报告、做频数表可用「标签（label）」。同一分析流程不要混用两种编码。
5. 时间：大项目请避开工作日上午集中录入高峰；优先低峰或夜间。
6. 落地位置：含个人敏感信息的文件不要发到微信、个人邮箱或网盘公开链接。放到项目约定的加密盘或学校/医院受控存储。

---

3. 网页导出：推荐操作规范

3.1 优先用报表，而不是「全部字段」

全项目一次性导出（所有仪器 + 所有字段 + 附件）是最慢、最容易超时的方式。建议：

1. 左侧 报表 → 新建报表，只勾选本次分析需要的字段（务必保留 record_id 及事件/实例字段）。
2. 用筛选条件限制记录（例如入组日期、中心、完成某份知情同意）。
3. 在报表页直接 导出数据，或到「数据导出」里选择该报表。

纵向研究、重复测量（如每次随访一张表）尤其不要一次拉成超宽表。按仪器分批导出，到 R 里再合并，通常更快、也更不容易把变量名弄乱。

3.2 数据导出页上的选项怎么选

进入 应用程序 → 数据导出、报表与统计：

• 导出格式：统计分析选 CSV / Microsoft Excel（CSV）。R 用 UTF-8 CSV；若 Excel 打开中文乱码，用「数据 → 自文本」指定 UTF-8，或在 R 里读入后再写出 xlsx。
• 原始值或标签：建模、对接其他库用 raw；制表用 label。建议同时导出一份数据字典，避免日后对不上编码。
• 复选框：每个选项会变成单独的 0/1 列。这是正常现象，不要手工改列名。
• 调查字段：不需要完成时间、完成状态时不要勾选，少拉无用列。
• 文件字段：除非本次就要附件，否则 不要 勾选导出所有上传文件。附件会显著增加等待时间，并产生大量本地文件。
• 去标识：能去标识就去标识。导出「完整数据集」会写入 Logging，属于可审计的敏感操作。

3.3 大项目怎么拆

按下面任一维度拆开，多次导出再合并：

• 按 仪器 / 访视（基线、随访 1、随访 2）
• 按 DAG / 中心
• 按 记录号段 或入组日期
• 先导出核心结局与协变量，需要时再补人口学或实验室子表

经验：分析用的「瘦表」往往只有几十个字段。先把瘦表跑通模型，再考虑是否需要补充字段。

3.4 Logging 导出（仅监查）

应用程序 → Logging → 用 日期、用户、记录号 过滤后再导出 CSV。无过滤导出全历史会很慢，且文件对统计分析没有帮助。

---

4. 用 API 导出：流程与示例

平台已启用 API。适合：定期拉数、R/Python 可重复分析、大项目分批、与统计脚本衔接。不适合：临时看一眼几条记录（用报表即可）。

4.1 一次性准备

1. 项目左侧 用户权限：为自己（或数据管理员角色）勾选 API 导出。需要写回数据时才开「API 导入」，分析人员默认不要开导入。
2. 打开 应用程序 → API：

- API URL 为：https://www.wcrcnet.cn/redcap/api/ - 点击生成 API token（32 位十六进制）。每人每项目一个 token，权限等于该用户在本项目的导出权限。

1. 把 token 存到本机环境变量或密钥库，不要写进 R 脚本、Word、邮件、微信、Git 仓库或聊天记录。
2. 人员离组后：在 API 页 删除 / 重新生成 token。

4.2 Token 怎么安全存放（Windows / R）

Windows PowerShell（当前用户，永久）：

[System.Environment]::SetEnvironmentVariable(
  "REDCAP_API_TOKEN",
  "在此粘贴您的token",
  "User"
)

新开一个终端后，R 中用 Sys.getenv("REDCAP_API_TOKEN") 读取。更稳妥可用 R 包 keyring（见第 5 节）。

4.3 最小 HTTP 示例

把 YOUR_TOKEN 换成环境变量中的值。以下只导出两个字段、JSON 格式，便于测试连通：

curl.exe -X POST "https://www.wcrcnet.cn/redcap/api/" ^
  -d "token=YOUR_TOKEN" ^
  -d "content=record" ^
  -d "format=json" ^
  -d "type=flat" ^
  -d "fields=record_id,age"

成功时返回 JSON 数组。若返回 {"error":"..."}，常见原因是 token 错误、未授权 API 导出，或字段名写错。

4.4 常用参数（记录导出）

参数	含义	建议
content	record 导出记录；metadata 数据字典；report 按报表 ID	日常分析优先 report 或带 fields / forms 的 record
format	json / csv / xml	R 用 csv 或 json 均可
type	flat 一行一条记录；eav 长表	大而稀疏的项目用 eav 再在 R 中透视，往往更稳
fields	逗号分隔的变量名	强烈建议只列需要的字段
forms	仪器名	按访视/仪器拆批
records	记录 ID 列表	抽查或按号段导出
events	纵向事件名	纵向项目必填其一或按事件拆
rawOrLabel	raw 或 label	分析用 raw
filterLogic	如 [age] >= 18	服务端过滤，减少传输
exportFiles	是否带文件	默认不要开

按已保存报表导出时：content=report，并提供 report_id（报表页 URL 或报表列表中可见）。报表在网页里筛好字段后，API 与网页结果一致，便于和统计程序对齐。

4.5 分批，避免一次拉爆

API 与网页导出占用的是同一套项目数据。一次请求字段过多、记录过多时，可能超时。做法：

• 用 fields / forms / filterLogic 缩小范围；
• 或按记录号分段（例如每 100～500 条一次）；
• R 包 REDCapR::redcap_read() 默认按批次拉取并拼接，一般不必自己写循环。

---

5. 建议安装的 R 包

包	角色	什么时候用
REDCapR	日常首选	redcap_read() 自动分批，适合大多数流行病与临床试验分析
redcapAPI	类型更严	exportRecordsTyped() 按字段类型转换日期、因子；exportReportsTyped() 导出报表
keyring	存 token	避免 token 出现在脚本里
tidyverse	整理	readr / dplyr / tidyr 做合并与透视
REDCapTidieR	复杂结构	纵向 + 重复测量需要按仪器拆成多个 tibble 时
tidyREDCap	辅助	复选框、下拉选项的标签处理

安装（CRAN）：

install.packages(c(
  "REDCapR",
  "redcapAPI",
  "keyring",
  "tidyverse",
  "REDCapTidieR"
))

不建议把 token 写在 ~/.Rprofile 明文里；用环境变量或 keyring。

---

6. R 示例代码

以下示例使用平台 API 地址。请把字段名、仪器名、报表 ID 换成您项目中的真实名称。示例中的 age、sex 仅为占位。

6.1 用 keyring 保存 token（做一次即可）

# install.packages("keyring")
library(keyring)

key_set(
  service = "redcap-wcrcnet",
  username = "my_project"
)
# 弹出窗口时粘贴 API token，不要把它写进脚本

之后每次分析：

token <- key_get("redcap-wcrcnet", "my_project")
uri   <- "https://www.wcrcnet.cn/redcap/api/"

若已按 4.2 节设置了 Windows 环境变量，也可用：

token <- Sys.getenv("REDCAP_API_TOKEN")
if (!nzchar(token)) stop("未找到 REDCAP_API_TOKEN")

6.2 REDCapR：按字段分批导出（推荐入门）

library(REDCapR)
library(dplyr)

uri   <- "https://www.wcrcnet.cn/redcap/api/"
token <- keyring::key_get("redcap-wcrcnet", "my_project")

out <- redcap_read(
  redcap_uri   = uri,
  token        = token,
  fields       = c("record_id", "age", "sex", "enroll_date"),
  raw_or_label = "raw",
  batch_size   = 200,
  verbose      = TRUE
)

if (!isTRUE(out$success)) {
  stop(out$outcome_message)
}

dat <- out$data
glimpse(dat)

只导出某一仪器：

out_form <- redcap_read(
  redcap_uri = uri,
  token      = token,
  forms      = c("baseline"),
  batch_size = 200
)
baseline <- out_form$data

导出数据字典（变量名与标签）：

meta <- redcap_metadata_read(redcap_uri = uri, token = token)$data

6.3 redcapAPI：带类型转换的导出

library(redcapAPI)

uri   <- "https://www.wcrcnet.cn/redcap/api/"
token <- keyring::key_get("redcap-wcrcnet", "my_project")

rcon <- redcapConnection(url = uri, token = token)

# 按字段导出，并按 REDCap 字段类型转为 Date / factor 等
dat <- exportRecordsTyped(
  rcon,
  fields     = c("record_id", "age", "sex", "enroll_date"),
  batch_size = 200
)

# 导出项目里已保存的报表（把 12345 换成报表 ID）
# rpt <- exportReportsTyped(rcon, report_id = 12345)

exportRecordsTyped() 会按数据字典做类型转换，减少把日期读成字符、把编码读成数字后忘记标签的问题。旧函数 exportRecords() 已不推荐。

6.4 纵向项目：先瘦表，再按仪器合并

library(REDCapR)
library(dplyr)

read_form <- function(form_name) {
  redcap_read(
    redcap_uri = uri,
    token      = token,
    forms      = form_name,
    batch_size = 200,
    verbose    = FALSE
  )$data
}

core      <- read_form("eligibility")
baseline  <- read_form("baseline")
followup  <- read_form("followup_1")

# 按 record_id（及 event / instance）合并；列名以您项目为准
analysis <- core %>%
  select(record_id, age, sex) %>%
  left_join(
    baseline %>% select(record_id, bmi, sbp),
    by = "record_id"
  )

重复测量（同一仪器多实例）不要强行导出成超宽表。可使用 REDCapTidieR 按仪器拆成列表，或在长表格式下用 tidyr 处理。

6.5 读入网页导出的 CSV

若您坚持用网页导出的文件：

library(readr)

dat <- read_csv(
  "C:/data/my_project_DATA_NOHDRS_2026-09-09.csv",
  locale = locale(encoding = "UTF-8"),
  na     = c("", "NA", "na")
)

REDCap 网页导出有时会同时给出带标签表头与原始表头两个文件，请认准文件名，不要混用。

---

7. 常见问题

导出一直转圈或浏览器报超时。 缩小字段，改用报表，取消附件，按仪器或中心拆批；或改走 API + REDCapR::redcap_read()。大项目不要在采集高峰做全量导出。

Excel 打开 CSV 中文乱码。 文件本身是 UTF-8。请用 Excel「数据 → 自文本/CSV」指定 UTF-8，或直接在 R 里 readr::read_csv()。不要用记事本另存成 ANSI 后再分析。

复选框变成了很多列。 这是 REDCap 的标准导出方式（每个选项一列）。分析时按列名（如 symptom___1）使用；需要中文标签时对照数据字典。

API 返回无权限或空数据。 检查：token 是否属于当前项目；用户权限是否勾选 API 导出；DAG 是否限制了可见记录；fields 是否写成了字段标签而不是变量名（必须用变量名，如 record_id）。

Token 不小心发到了微信或邮件。 立刻在项目 API 页删除并重新生成，通知项目负责人。旧 token 视为已泄露。

能否把整库 mysqldump 当作「导出」？ 不能。那是系统运维备份，含全部项目与审计日志，不属于用户数据导出路径，也不应出现在个人电脑上。

---

8. 建议记住的几条规范

1. 分析用报表或字段清单，不用「全部字段 + 全部文件」。
2. 分析用 raw + 数据字典；对外表格再用 label。
3. Token 当密码管理；脚本只读环境变量或 keyring。
4. 大项目：按仪器 / 中心 / 记录号分批；R 用 REDCapR 或 exportRecordsTyped。
5. Logging 只为监查服务，导出时加时间窗。
6. 含直接标识符的文件按研究数据保管，不通过即时通讯传输。

使用中若网页导出持续失败，请向项目数据管理员提供：项目名（或 PID）、大约记录数、导出的是报表还是全部字段、是否勾选了文件、发生时间，以便平台侧协助排查。请勿在工单或邮件中粘贴 API token。