Taskwarrior 3.5.0 配置参数详解（.taskrc 逐项实测）
逐项实测 Taskwarrior 3.5.0 的 .taskrc 配置体系：task show/config/rc 覆盖/TASKRC 重定向四套操作，覆盖数据位置、默认行为、日期格式、report.* 报表定制、context、urgency 系数、颜色主题与 sync 组，含 report 前缀误写等排障实录与可用个人配置模板。
Taskwarrior 3.5.0 配置参数详解（.taskrc 逐项实测）
目标：在 Debian 12 服务器上对 Taskwarrior 3.5.0 的配置体系做逐项实测——参数的查看（
task show/task _show）、写入（task config）、命令行覆盖（rc.xxx=value）、环境变量重定向（TASKRC/TASKDATA），并对数据位置、默认行为、日期格式、报表定制、上下文、紧急度系数、颜色主题、同步等核心配置组逐项给出实测回显与解读。安装方法见《Taskwarrior 3.5.0 安装指南（发行版包与源码构建双线实测）》，命令全集见《Taskwarrior 3.5.0 常用 CLI 命令与工具详解》。
一、环境信息
| 项目 | 值（实测） |
|---|---|
| 操作系统 | Debian GNU/Linux 12 (bookworm)，x86_64 |
| Taskwarrior 版本 | 3.5.0（官方源码构建，/usr/local/bin/task） |
| 配置文件 | /root/.taskrc（首次运行自动创建的样例配置起步） |
| 数据目录 | /root/.task（内含 taskchampion.sqlite3） |
| 参照环境 | 同机另一 Debian 12 环境安装 taskwarrior 2.6.2（用于标注版本差异） |
💡 说明：
.taskrc是 Taskwarrior 唯一的用户配置文件（纯 KEY=VALUE 格式，支持include引入主题），任务数据本体在~/.task下，二者分工不要混淆。本文所有「实测回显」均来自上述环境真实执行。
二、前置条件
- 已按安装篇完成 Taskwarrior 3.5.0 安装并至少成功运行过一次（存在
~/.taskrc与~/.task/）；尚未安装的读者先完成安装篇的任一方案； - 命令在交互终端执行。⚠️ 本文多处用到
task config的写确认交互——在真实终端直接输入yes回车即可；若你在脚本/管道等非交互环境复现（确认提示读不到输入），可参照本文给出的 pty 方式（echo yes | script -qec "…" /dev/null），这也是下文回显中出现script -qec包装的原因。
三、参数查看与修改方式
3.1 查看：task show 与 task _show
task show 列出「生效中的全部配置」（含内建默认值），task _show 以 KEY=VALUE 形式输出（适合脚本解析，实测 245 行）：
task show | head -18
task _show | wc -l
实测回显：
Config Variable Value
_forcecolor 0
abbreviation.minimum 2
active.indicator *
alias.burndown burndown.weekly
alias.ghistory ghistory.monthly
alias.history history.monthly
alias.rm delete
allow.empty.filter 1
annotation.info 1
avoidlastcolumn 0
bulk 3
calendar.details sparse
calendar.details.report list
calendar.holidays none
calendar.legend 1
calendar.offset 0
245
查询单个键直接跟在 task show 后：task show gc、task show weekstart（实测回显见 4.2/4.3 节）。当某键与内建默认不同时，task show 会额外提示 Some of your .taskrc variables differ from the default values.（实测见 5.4 节）。
3.2 修改：task config 的写/改/删
写入或修改一个键（终端内会请求确认）：
task config default.command list
实测回显（交互确认后）：
Are you sure you want to add 'default.command' with a value of 'list'? (yes/no) Config file /root/.taskrc modified.
再次赋值时提示会变为 Are you sure you want to change the value of '_forcecolor' from '1' to '0'?（实测见 5.7 节）；带键不带值执行则请求删除该键：
Are you sure you want to remove 'reporter.mini.columns'? (yes/no) Config file /root/.taskrc modified.
⚠️ 首次踩坑提示：自定义报表的配置前缀是
report.<报表名>.*，不是reporter.…。实测误用reporter.mini.columns时 task 照样收下并写入，但报表渲染完全不生效——这类「写入成功但键名无效」的配置不会报错，排查方法是task show <键名>与task _show | grep <键名>比对。
3.3 临时覆盖：rc.键=值 命令行参数
任何配置都可在单次命令中用 rc.键=值 覆盖，不落盘。最直观的验证是关掉 verbose 提示新增任务：
task rc.verbose=nothing add silent task test
task count
实测回显：
5
对照正常执行 task add … 会有 Created task 5. 提示行，此处被覆盖后不再输出，task count 证实任务确实创建（总数 5）。
3.4 环境变量重定向：TASKRC / TASKDATA
mkdir -p /tmp/rct
TASKRC=/tmp/rct/rc TASKDATA=/tmp/rct/data task show data.location
实测回显：
TASKRC override: /tmp/rct/rc
TASKDATA override: /tmp/rct/data
Cannot proceed without rc file.
解读：TASKRC/TASKDATA 被优先采用并回显 override 提示；但与首跑交互不同，显式指定的 TASKRC 文件不存在时 task 不会主动创建样例配置，需先提供配置文件（哪怕空文件）。这套机制是多实例/多账户隔离的基础（安装篇 8.3 节的多版本隔离即用此法）。
3.5 样例配置文件与 XDG 位置
3.5.0 首跑自动创建的样例 ~/.taskrc 实测全文：
# [Created by task 3.5.0 10/24/2026 10:03:29]
data.location=/root/.task
news.version=3.5.0
# To use the default location of the XDG directories,
# move this configuration file from ~/.taskrc to ~/.config/task/taskrc and update location config as follows:
#data.location=~/.local/share/task
#hooks.location=~/.config/task/hooks
# Color theme (uncomment one to use)
include default.theme
#include light-16.theme
#include light-256.theme
#include bubblegum-256.theme
#include dark-16.theme
#include dark-256.theme
#include dark-red-256.theme
#include dark-green-256.theme
#include dark-blue-256.theme
#include dark-violets-256.theme
#include dark-yellow-green.theme
#include dark-gray-256.theme
#include dark-gray-blue-256.theme
#include solarized-dark-256.theme
#include solarized-light-256.theme
#include no-color.theme
逐项解读：data.location 指数据目录（默认 ~/.task）；news.version 记录已读版本公告；注释块给出 XDG 化的官方路径——把文件移到 ~/.config/task/taskrc 并把数据改到 ~/.local/share/task；include 行启用配色主题（默认 default.theme，取消注释即可切换，见 5.7 节）。
四、参数总览
按功能域分组（组内键名为 3.5.0 实测存在者，默认值取自 task show 实测）：
| 功能域 | 代表键 | 默认值（实测） |
|---|---|---|
| 数据位置 | data.location | /root/.task |
| 默认行为 | default.command / gc / bulk / allow.empty.filter / abbreviation.minimum | next（未设置时）/ 1 / 3 / 1 / 2 |
| 提示输出 | verbose / nag / active.indicator | affected,blank,context,edit,header,footnote,label,new-id,news,project,special,sync,override,recur / 空 / * |
| 日期显示 | dateformat / dateformat.report / dateformat.info / dateformat.holiday / weekstart | m/d/Y（未覆盖时）/ 空（回退 dateformat）/ Y-M-D H:N:S / YMD / sunday |
| 报表定制 | report.<名>.columns / .labels / .sort / .filter | 无（内建 list/next/long 等） |
| 上下文 | context.<名>.read / .write | 无 |
| 紧急度 | urgency.*.coefficient（约 20 项） | 见 5.6 节实测表 |
| 颜色主题 | include *.theme / color / _forcecolor | default.theme / off（非 TTY）/ 0 |
| 同步 | purge.on-sync / sync.server.* | 0 / 空（未配置） |
| 别名 | alias.rm / alias.history / alias.burndown / alias.ghistory | delete / history.monthly / burndown.weekly / ghistory.monthly |
💡 说明：3.5.0 的
task _show全量输出 245 行，上表只覆盖日常运维最高频的键；全量清单以本机task show为准（版本间默认值偶有差异，如 weekstart 在 2.6.2 参照环境中同为 sunday）。
五、核心配置组逐项实测
5.1 数据与钩子位置：data.location
task show data.location
实测回显：
data.location /root/.task
数据目录落盘形态（实测 ls -la ~/.task/）：
drwxr-xr-x 2 root root 4096 Oct 24 10:03 .
drwx------ 1 root root 4096 Oct 24 10:03 ..
-rw-r--r-- 1 root root 45056 Oct 24 10:03 taskchampion.sqlite3
解读：3.5.0 的任务数据由 TaskChampion 引擎管理，本地落为单个 SQLite 库文件 taskchampion.sqlite3（2.6.2 时代是 pending.data 等 JSON 文件族，备份迁移方式见安装篇 7.3 节）。改 data.location 等价于换库位置，改后建议 task diagnostics 核对 Data: 行已指向新目录。
5.2 默认行为组：default.command / gc / bulk / nag / verbose
default.command——裸敲 task 不带子命令时执行的默认命令（实测设为 list 后生效）：
default.command=list
gc——垃圾回收开关（控制已完成任务在报表中的即时收纳），实测 task show gc：
Config Variable Value
gc 1
bulk——批量操作超过该数量时请求确认，默认 3（实测 task show 片段 bulk 3）。
nag——完成低紧急度任务时的提醒文案。实测设置并触发：
echo yes | script -qec "task config nag You have more urgent tasks." /dev/null
task 3 done
实测回显（done 的完整输出）：
Completed task 3 'low priority task'.
Completed 1 task.
You have more urgent tasks.
The project 'demo' has changed. Project 'demo' is 50% complete (1 of 2 tasks remaining).
验证判定：nag 文案紧随 Completed 1 task. 出现——因为当时存在更高紧急度（priority:H）的待办任务，触发了提醒；清空更高紧急度任务后完成操作则不再出现。不想要提醒时 task config nag（无值）删除即可。
verbose——输出开关集合，默认值实测：
verbose affected,blank,context,edit,header,footnote,label,new-id,news,project,special,sync,override,recur
需要安静输出时用覆盖方式（见 3.3 节），或把值改为 affected,new-id 等最小集。
5.3 日期与显示组：dateformat 系列 / weekstart
task show weekstart
task show dateformat
实测回显：
Config Variable Value
weekstart sunday
dateformat.holiday YMD
dateformat.info Y-M-D H:N:S
dateformat.report
实测把报表日期格式改为 Y/m/d 后，task list 的 Due 列立即变化：
echo yes | script -qec "task config dateformat.report Y/m/d" /dev/null
task list
实测回显：
ID Age P Project Tags Due Description Urg
-- ---- - ------- ----- ---------- ------------------------- ----
1 9min 2026/10/30 pay electricity bill 6.25
3 1min H demo urgent top task 7
2 9min docs learn read taskwarrior docs 1.8
解读：dateformat.report 为空时回退 dateformat（默认 m/d/Y，即 10/30/2026）；改为 Y/m/d 后显示 2026/10/30。日期占位符语法：Y=四位年、m=月、d=日、H:N:S=时分秒，完整表见官方 man taskrc。weekstart 影响日历报表与「本周」类过滤的周起始日，默认 sunday，中文环境常改为 monday。
5.4 报表定制组：report.<名>.* 全链实测
定义一个只看 ID/截止日/描述的最小报表并验证（列→标签→排序→过滤四步）：
echo yes | script -qec "task config report.mini.columns id,due,description" /dev/null
echo yes | script -qec "task config report.mini.labels ID,Due,Description" /dev/null
echo yes | script -qec "task config report.mini.sort due+" /dev/null
echo yes | script -qec "task config report.mini.filter status:pending" /dev/null
task mini
实测回显（逐步 Config file /root/.taskrc modified. 后运行报表）：
ID Due Description
-- ---------- ---------------------
1 2026-10-30 pay electricity bill
2 read taskwarrior docs
3 urgent top task
逐项解读：report.mini.columns 定义列（列名即字段名）；.labels 定义表头文字；.sort 定义排序（due+ 升序，- 为降序）；.filter 定义报表内置过滤器。⚠️ 两个实测教训：其一，前缀必须是 report. 而非 reporter.（误前缀写入成功但报表不识别，见 3.2 节）；其二，自定义报表若不设 .filter，已完成任务也会出现——实测未加过滤时 task mini 多显示一行 low priority task（Due 为 - 的已完成任务），加上 status:pending 后消失，这正是内建报表与自定义报表的默认差异所在。task show 对自定义键会追加差异提示（实测）：
Some of your .taskrc variables differ from the default values.
5.5 上下文组：context.<名>.* 实测
上下文（context）是「一键给所有查询叠加过滤器」的配置组。实测定义、启用、查看、关闭：
echo yes | script -qec "task context define work project:demo" /dev/null
task context work
task list
task context
task context none
实测回显（定义时 task 自动写入一对键）：
Are you sure you want to add 'context.work.read' with a value of 'project:demo'? (yes/no) Are you sure you want to add 'context.work.write' with a value of 'project:demo'? (yes/no) Context 'work' defined (read only). Use 'task context work' to activate.
Context 'work' set. Use 'task context none' to remove.
启用后 task list 只剩 demo 项目的 1 条任务，且表头上方多出 Context 'work' set. 提示；task context 查看状态：
Name Type Definition Active
work read project:demo no
write no
task context none 关闭（实测回显 Context unset.）。解读：define 一次会写 context.work.read（查询过滤）与 context.work.write（新增任务自动附加属性）两个键；task config 也可直接管理这两个键，效果等同。
5.6 紧急度系数组：urgency.*
task show urgency 实测回显（节选）：
Config Variable Value
urgency.active.coefficient 4.0
urgency.age.coefficient 2.0
urgency.age.max 365
urgency.annotations.coefficient 1.0
urgency.blocked.coefficient -5.0
urgency.blocking.coefficient 8.0
urgency.due.coefficient 12.0
urgency.inherit 0
urgency.project.coefficient 1.0
urgency.scheduled.coefficient 5.0
urgency.tags.coefficient 1.0
urgency.uda.priority.H.coefficient 6.0
解读：Urg 列的分数就是各系数加权求和（如 due 临近贡献最高 12 分、优先级 H 贡献 6 分、被阻塞任务倒扣 5 分）。调参思路：想让「截止日期」压倒一切就调大 urgency.due.coefficient；团队内想让「阻塞他人」更醒目就调大 urgency.blocking.coefficient。改系数后用 task list 观察 Urg 列变化验证即可。
5.7 颜色与主题组：include / color / _forcecolor
主题通过 include 行切换（样例文件列出全部 15 个可选主题，见 3.5 节）。实测切换到 solarized-dark-256：
sed -i 's|^include default.theme|include solarized-dark-256.theme|' ~/.taskrc
task show color
非 TTY 输出时颜色自动关闭，实测提示：
Color is currently turned off in your .taskrc file. To enable color, remove the line 'color=off', or change the 'off' to 'on'.
强制在管道/重定向输出中也保留 ANSI 颜色，实测设 _forcecolor=1 后图例出现转义序列：
Here are the colors currently in use:
Color Definition
^[[1;31mcolor.active ^[[0m ^[[1;31mbold red ^[[0m
解读：color=on 让 TTY 会话启用配色；_forcecolor=1 是非交互场景（如需要彩色日志落盘）的强制开关，日常保持 0。include no-color.theme 可一键退回无色。配色具体规则键（color.active、color.overdue 等）都由主题文件给出，可在其后用 task config color.<对象> <样式> 覆盖。
5.8 同步组：sync.*（未配置时的实测基线）
task show sync
实测回显：
Config Variable Value
color.sync.added rgb010
color.sync.changed color11
color.sync.rejected color9
purge.on-sync 0
解读：未配置同步服务端时，sync.server.url / sync.server.client_id / sync.encryption_secret 三键为空——这是 3.x 同步的三要素（服务端地址、本机客户端 ID、端到端加密口令），配置方法属于同步部署主题；purge.on-sync=0 表示同步时不清理已完成任务历史。
5.9 别名组：alias.*
实测默认别名（task show 片段）：
alias.burndown burndown.weekly
alias.ghistory ghistory.monthly
alias.history history.monthly
alias.rm delete
解读：alias.rm=delete 意味着 task 3 rm 等价于删除（软删除）；自定义示例：task config alias.today "list due:today" 后即可 task today。别名只是文本替换，任何内建命令都能被覆盖映射。
六、个人配置模板（实测可用的起步集）
以下模板整合本文全部实测项，适用于「单机个人使用、终端 TTY、希望安静且聚焦」的场景（直接追加到 ~/.taskrc，逐行含义见注释）：
# ── 位置 ─────────────────────────────────────────────
data.location=~/.task # 任务库位置（默认值，显式写出便于备份脚本引用）
# ── 默认行为 ─────────────────────────────────────────
default.command=list # 裸敲 task 时执行的报表
gc=1 # 保持垃圾回收开启
bulk=3 # 批量完成超过 3 条时请求确认
nag=You have more urgent tasks. # 完成低紧急度任务时提醒（不需要可整行删除）
# ── 显示 ────────────────────────────────────────────
verbose=affected,new-id,project # 只保留必要提示，屏蔽 header/footnote 等噪音
weekstart=monday # 周从周一开始
dateformat.report=Y-m-d # 报表日期统一 2026-10-30 形态
# ── 报表 ────────────────────────────────────────────
report.mini.columns=id,due,description
report.mini.labels=ID,Due,Description
report.mini.sort=due+
report.mini.filter=status:pending # 自定义报表务必带过滤，否则已完成任务混入
# ── 上下文（按需启用）───────────────────────────────
context.work.read=project:Work
context.work.write=project:Work
# ── 颜色 ────────────────────────────────────────────
include solarized-dark-256.theme # 主题；无色需求改 include no-color.theme
color=on # TTY 会话启用配色；_forcecolor 保持默认 0
💡 说明：该模板不含任何同步键（单机场景）。模板中每一项均在本文对应小节实测过，逐项粘贴后可用
task show复核差异提示与task diagnostics做整体体检。
七、常见问题（FAQ）
Q1：task config 写入后报表/行为没变化？
先查键名前缀是否正确——自定义报表是 report.<名>.*（实测误写 reporter. 前缀不生效，见 3.2 节排障）。再用 task show <键> 或 task _show | grep <键> 确认键确实存在且值正确。
Q2：task config 没有出现 yes/no 确认，直接 No changes made.？
确认提示从终端读取输入，非交互环境（脚本、CI、重定向）读不到。交互终端直接运行即可；脚本内用 pty 包装（echo yes | script -qec "task config …" /dev/null，本文全部写操作实测即用此法），或直接编辑 ~/.taskrc 文本文件——两者等效，文件格式就是 KEY=VALUE。
Q3：TASKRC=/path/rc task … 提示 Cannot proceed without rc file.？
显式指定 TASKRC 时文件不存在不会自动创建（与默认路径首跑行为不同，见 3.4 节实测）。先创建文件（空文件亦可）再执行。
Q4：为什么管道输出没有颜色，color=on 也没用？
非 TTY 输出时 task 自动关闭颜色；需要彩色落盘/进管道时设 _forcecolor=1（实测出现 ANSI 转义序列，见 5.7 节）。
Q5：改了 urgency 系数，Urg 分数怎么没变？
Urg 是实时计算的，确认改动写入（task show urgency 核对）后重新渲染报表即可；urgency.age.max（默认 365）会封顶「任务年龄」贡献的老化分数，老化类系数调整要看长任务才明显。
Q6：配置改坏了怎么回滚？
单键回滚：task config <键>（无值）确认删除，即回到内建默认。整体回滚：停止使用当前 ~/.taskrc，重命名后任由 task 重建样例（或从 3.5 节样例全文手工恢复），数据目录 ~/.task 与配置文件相互独立，删除配置不影响任务数据。
八、参考链接
- 官方文档（配置章节）：https://docs.taskwarrior.org/
- man 手册：
man taskrc（安装后位于 /usr/local/share/man/man5/taskrc.5，实测随 3.5.0 安装分发） - 样例配置：首次运行自动生成于 ~/.taskrc（全文见 3.5 节）
- 安装与环境准备：《Taskwarrior 3.5.0 安装指南（发行版包与源码构建双线实测）》
- 定位与选型背景：《Taskwarrior 3.5.0 介绍与选型指南》