企业官网建设流程全解析

1. 先把话说清楚：kaggle 命令到底解决了什么问题

如果你已经习惯在浏览器里点开数据集页面、手动点 Download、等压缩包落到 Downloads 文件夹、再拖进项目目录，那么第一次听说kaggle这个命令行工具时，大概率会觉得“这不是多此一举吗”。我当初也是这么想的，直到有一次要在三台机器上复现同一个实验，光是把数据放到正确的位置就花掉了一个下午。从那之后，kaggle命令安装这件事就被我列进了新机器初始化的必做清单里。

简单说，kaggle是一个官方维护的 Python 包，装上之后你的终端里就多了一条叫kaggle的命令。它能做的事情覆盖了平台上大部分需要鼠标点击的动作：搜索数据集、下载竞赛数据、查看排行榜、提交结果、上传自己的数据集和 notebook、管理已有版本。它把“打开网页 → 找到按钮 → 点一下 → 等下载”这一串动作，压缩成一行可复制的命令，而且这一行命令可以被写进脚本、写进 CI 配置、写进队友的 README。

这篇文章面向的是这么几类人：刚接触数据科学竞赛、想摆脱手动下载的初学者；需要把数据流水线自动化的工程师；以及那些在远程服务器上没有图形界面、只能靠终端干活的同学。后一类人其实是最刚需的，因为服务器上根本没有浏览器给你点。全文会从安装讲起，一路走到认证配置、常用命令、多账号隔离和报错排查，中间穿插我自己踩过的坑。技术门槛不高，但魔鬼全在细节里。

1.1 网页端操作的三个硬伤

第一个硬伤是不可复现。你在网页上点了一个数据集下载，三个月后同事问你这个 CSV 是从哪来的，你只能回忆起“好像是某个房价数据集”。而命令行留下的是一条明确的指令，指令里有数据集的所有者、名字、版本号，任何人拿到这条指令都能拉到和你一模一样的东西。科研和工程里最贵的成本从来不是算力，而是“我这边跑得通，你那边跑不通”。

第二个硬伤是批量操作低效。你要下载十个数据集，网页端就是十次点击加十次解压；命令行是一行 for 循环，或者干脆写一个 shell 脚本，去喝杯咖啡回来就齐了。上传也是同理，一个数据集有二十个版本要更新描述，手工点击点到手抽筋。

第三个硬伤是远程环境不可用。云主机、容器、实验室的共享服务器，这些地方通常只有 SSH。你在本地下载好再scp上去，一个几十 GB 的数据集传一晚上，中间断一次就得重来。用kaggle datasets download直接在服务器上拉，快得多，也不占用你本地带宽。

1.2 命令行工具的本质：一层薄薄的 REST 封装

理解这一点很重要，能帮你少走很多弯路。kaggle这个包本身不存储任何数据，它做的事情是：读取你本地的凭证文件 → 拿凭证去换取访问权限 → 按照你给的参数拼接一个 HTTP 请求 → 把返回的数据写成本地文件。所以它本质上是一个“带认证的下载器 + 上传器”。

这个认知带来三个直接推论。第一，网络不通它一定失败，而且报错信息往往很含蓄，容易让人误以为是凭证问题，实际是连接问题。第二，权限问题一定出在凭证或平台侧规则上，不在命令参数上，所以排查方向应该是核对 token 有没有过期、有没有在网页上接受竞赛规则。第三，它不会帮你做数据清洗，下载下来是原始压缩包，解压、编码、字段类型这些事还是得你自己来。

我见过不少人把kaggle当成某种“魔法同步工具”，以为装完就能在自己的项目里自动出现数据，结果在目录里翻半天找不到文件。它默认会把东西下到当前工作目录，文件名叫什么、解压到哪，全看你传了哪些参数。

1.3 谁适合把这条路走一遍

如果你只是偶尔下一次公开数据集，一两个月才用一次，网页端其实够用，不必折腾。但只要满足下面任意一条，我建议你花十分钟把命令装好：需要重复下载同一份数据超过三次；需要在无图形界面的环境里工作；需要把数据获取写进自动化脚本；需要管理自己上传的数据集版本；需要批量提交多个模型的结果做对比。

最后一条尤其值得说。做竞赛的时候，一天提交十几次是常态，每次都在网页上选文件、填描述、点提交，效率极低还容易点错。命令行提交可以配合脚本做“训练完自动提交并记录分数”，把整个闭环串起来。这部分后面会给出具体写法。

2. 装之前的准备：环境、版本与依赖关系

很多人装kaggle失败，问题根本不在kaggle本身，而在 Python 环境早就乱了。所以这一节不讲安装命令，先讲环境。我个人的经验是：凡是涉及“命令行工具”的安装，先花两分钟确认解释器和包管理器，能省掉后面半小时的排错。

2.1 Python 版本与包管理器怎么选

kaggle是纯 Python 包，理论上 Python 3.7 以上都能跑，但我实测下来建议用 3.9 到 3.11 这个区间。太老的版本会遇到依赖项（尤其是urllib3、certifi这类底层库）拉不到合适版本的问题；太新的版本（比如刚出的 3.13）则可能因为某些依赖还没出预编译包，触发源码编译，在 Windows 上尤其痛苦。

包管理器方面，pip是唯一稳妥的选择。有人会问能不能用conda装，我的建议是不要在 conda 的 base 环境里混装。如果你确实想用 conda 管理，正确姿势是conda create一个独立环境，然后在这个环境里用pip install kaggle，而不是conda install kaggle——后者更新往往滞后，版本可能停在很老的地方，缺一些新命令。

还有一个经常被忽略的点：确认你用的pip和你想用的python是同一个。在同时装了多个 Python 的机器上，pip install装到了 A 解释器，你运行kaggle时用的却是 B 解释器的路径，结果就是“明明装了却说 command not found”。验证办法很简单：

python -c "import sys; print(sys.executable)" pip -V

两条命令输出的路径前缀应该指向同一个环境目录。如果不一致，用python -m pip install kaggle来安装，这样能强制把包装到你当前python对应的那个环境里。这个小技巧我几乎每次在新机器上都会用，比记各种pip3、pip3.11的别名靠谱多了。

2.2 虚拟环境不是仪式感，是止损手段

我知道很多人看到“建议使用虚拟环境”这行字就直接跳过。但这个包的依赖里包含requests、python-dateutil、urllib3、certifi、tqdm等常见库，而你的主环境里大概率已经装了这些库的某个版本。版本一冲突，轻则kaggle报奇怪的ImportError，重则把你原来能跑的项目搞挂。

我遇到过一次典型事故：在一个老项目环境里装了kaggle，结果urllib3被顺带升级到了 2.x，而项目里另一个依赖只兼容 1.x，第二天整个服务起不来。排查了半天才发现是装命令行工具带出来的连锁反应。从那以后我给自己定了规矩：任何 CLI 工具都装在独立环境里，用的时候激活，不用就放着。

创建和使用的方式很直接：

python -m venv ~/.venvs/kaggle-cli source ~/.venvs/kaggle-cli/bin/activate # Windows 用 .\.venvs\kaggle-cli\Scripts\activate pip install --upgrade pip pip install kaggle

在 Windows 上路径是%USERPROFILE%\.venvs\kaggle-cli\Scripts\activate.bat。如果你不想每次都手动激活，可以把这个环境的bin（或Scripts）目录加到PATH里，这样kaggle命令全局可用，同时依赖又被隔离在独立环境中，算是两全其美。

2.3 依赖清单与版本冲突的预判

安装之前，如果你好奇这个包会带进来什么，可以先看一眼依赖，做到心里有数：

pip index versions kaggle pip download kaggle --no-deps -d /tmp/kaggle-check

第二条命令只下载 wheel 不安装，配合unzip -p /tmp/kaggle-check/*.whl '*/METADATA' | grep Requires-Dist就能看到完整的依赖声明。这招在离线环境或者需要审计依赖的团队里特别有用。

关于版本，我的建议是不要锁死小版本。这个工具的迭代节奏比较稳，向后兼容做得还行，锁死版本反而会在换机器时制造麻烦。真要锁，就锁在requirements.txt里写kaggle>=1.5,<2.0这种范围，既避免大版本突变，又不会因为小版本缺失装不上。

3. kaggle 命令安装全过程拆解

准备工作做完，真正的安装其实只有一行。但“装完”和“能用”之间还隔着验证和认证两道关卡，很多人卡在第二关就放弃了。这一节把三关连起来讲。

3.1 标准安装：三条命令走完全程

在已经激活的虚拟环境里，依次执行：

# 1. 升级 pip，避免因为 pip 太老拉不到最新 wheel python -m pip install --upgrade pip # 2. 安装 kaggle 命令行工具 python -m pip install kaggle # 3. 确认安装位置和版本 pip show kaggle

pip show的输出里有两个字段值得看：Version告诉你装的是哪个版本，Location告诉你包被装到了哪个site-packages。如果Location指向的路径和你的虚拟环境目录对不上，说明装错地方了，回到 2.1 节检查解释器。

如果你在企业内网或者网络条件一般，可以在pip install后面加-i指定国内镜像源，或者加--timeout 60放宽超时。这一步本身不复杂，但下载中断过一次之后pip的缓存可能会留下半截文件，导致重装报hash mismatch，这时候加--no-cache-dir强制重下即可。

另外补一句常见误区：Windows 上不需要管理员权限。装在用户目录的虚拟环境里，普通权限就够。用管理员权限开终端装包，反而容易装到系统级site-packages，日后卸载不干净。

3.2 安装后的第一件事：验证而非庆祝

装完立刻敲下面两条：

kaggle --version kaggle --help

第一条输出类似Kaggle API 1.6.x的版本号，说明可执行文件已经进了PATH。如果报command not found或'kaggle' 不是内部或外部命令，说明脚本目录没在PATH里，用python -m kaggle --version先验证包本身没问题，再去补PATH。

第二条会打印所有可用子命令，大概长这样（节选）：

available commands: competitions List competitions, download files, submit datasets List, download, create, update datasets kernels Manage notebooks/kernels config Set or view configuration

这一步的价值在于确认命令树完整。有时候装的是个很老的版本，datasets version之类的子命令根本没有，你在后面照着教程敲就会一直报invalid choice。遇到这种情况，pip install --upgrade kaggle升级一下就好。

我习惯在验证之后顺手跑一条只读的查询命令，比如kaggle competitions list -s "titanic"。这条命令会真正走一次网络请求和认证流程，能一次性暴露“网络不通”“凭证缺失”“token 失效”这三类问题，比等到后面下载大文件时才报错要划算得多。

3.3 凭证配置：kaggle.json 从哪来、放哪去

命令装好只是有了工具，能不能用取决于凭证。凭证是一个叫kaggle.json的小文件，里面就两个字段：用户名和一串 API Key。

获取路径是在平台网站上进入个人账户设置页，找到 API 区块，点击创建新的 token。浏览器会下载一个kaggle.json给你。这个文件只会下载一次，页面上不会让你再次查看完整 Key，如果丢了只能重新生成一个（旧的同时失效）。所以拿到之后立刻做两件事：备份到密码管理器，以及放到正确的位置。

注意：不要把kaggle.json提交到任何 Git 仓库。它等价于你账号的密码，泄漏之后别人可以用你的配额下载、上传甚至删除数据集。.gitignore里第一行就该写它。

存放位置分平台：

创建目录并放入文件：

mkdir -p ~/.kaggle mv ~/Downloads/kaggle.json ~/.kaggle/kaggle.json chmod 600 ~/.kaggle/kaggle.json

第三行的chmod是必须做的。这个包在读取配置文件时会检查权限，如果发现文件对其他用户可读，会直接抛一个Permissions too open的错误并拒绝加载。这不是它矫情，是防止在共享服务器上你的密钥被同机器其他人读走。Windows 上不需要这一步，NTFS 的默认权限模型不一样。

3.4 三个平台的路径差异与权限设置

Linux 和 macOS 的坑主要集中在chmod和家目录符号链接上。如果你用的是容器，$HOME可能被设成了/root或者干脆没设，这时候~/.kaggle展开的位置可能出乎意料。稳妥做法是先echo $HOME看一眼，再用绝对路径确认文件确实在那儿：

echo $HOME ls -la $HOME/.kaggle/

Windows 的坑则集中在路径长度和转义上。C:\Users\<用户名>里的用户名如果包含中文或空格，某些老版本会有编码问题，表现为“文件明明在那儿却说找不到”。解决办法不是改用户名（风险太大），而是用KAGGLE_CONFIG_DIR指向一个纯英文无空格的路径，比如D:\kagglecfg。这个办法我帮至少三个朋友解决过同类问题。

还有一个跨平台细节：Windows 上的换行符。如果你手动编辑kaggle.json（比如从别处粘贴内容），记事本可能存成 CRLF 或者带 BOM，导致 JSON 解析失败，报Expecting value: line 1 column 1。用 VS Code 存成 UTF-8 无 BOM 就行，或者干脆别手写，直接用下载下来的原文件。

3.5 用环境变量绕开配置文件

有些场景下你没法往家目录写文件：容器里每次重启都重置、CI 环境里没有持久化磁盘、共享集群的家目录是只读的。这时候可以把凭证直接塞进环境变量：

export KAGGLE_USERNAME="your_username" export KAGGLE_KEY="your_api_key"

设置好之后，kaggle会优先读这两个变量，不再找kaggle.json。在 CI 里，把这两个值配成仓库的加密变量，脚本里就不用出现明文了。

需要提醒的是优先级顺序：环境变量优先于配置文件。如果你在本地既配了文件又设了环境变量，调试时可能会被“为什么改了文件没生效”困扰半天。排查时先env | grep KAGGLE看一眼有没有残留的变量。

另外，环境变量方式有个隐性风险：它会被同一 shell 里启动的所有子进程继承。如果你在这台机器上跑别人的脚本，那些脚本也能拿到你的凭证。所以我的做法是只在当前终端会话里export，不写进.bashrc，任务结束就关窗口。

4. 认证配置的深水区与多环境隔离

凭证放对了，基础使用就没问题。但只要你的工作稍微复杂一点——比如同时有个人账号和团队账号，或者需要在测试环境和生产环境之间切换——就会撞上配置管理的问题。这一节讲的是“装好之后怎么管”。

4.1 KAGGLE_CONFIG_DIR：一个变量解决多账号

KAGGLE_CONFIG_DIR这个变量的作用是告诉工具“去这个目录里找kaggle.json”，而不是默认的家目录。利用它，你可以做很干净的账号隔离：

# 账号 A mkdir -p ~/.kaggle-a && cp ~/Downloads/kaggle-a.json ~/.kaggle-a/kaggle.json # 账号 B mkdir -p ~/.kaggle-b && cp ~/Downloads/kaggle-b.json ~/.kaggle-b/kaggle.json

用的时候临时指定：

KAGGLE_CONFIG_DIR=~/.kaggle-a kaggle datasets list -m

这种“前缀变量 + 命令”的写法只在当前这条命令生效，不污染环境，非常适合写进脚本。我给自己的项目写了两个小别名放在 shell 配置里，切账号就是敲两个字母的事，比改文件内容安全得多，因为改文件很容易忘记改回来。

一个实操心得：目录名别用账号名原文。用~/.kaggle-a这种中性命名，万一你哪天不小心把ls -la的输出截图发出去，也不会暴露账号信息。

4.2 权限泄漏的真实风险

前面提过chmod 600，这里展开讲为什么。多用户共享服务器上，家目录的默认权限常常是755，意味着同机器的其他用户能列出你目录里的文件。如果kaggle.json是644，别人可以直接cat出来你的 Key。这个风险在实验室服务器、公司跳板机上都是真实存在的。

验证方法：

ls -l ~/.kaggle/kaggle.json # 期望输出：-rw------- 1 user group ... kaggle.json

如果显示的是-rw-r--r--，就还是644，需要改。chmod 600之后只有属主可读写。

另一个容易忽略的点是备份文件。很多人cp kaggle.json kaggle.json.bak就放在同一个目录，然后只给原文件改了权限。备份文件还是 644，等于白改。要么别在同目录留备份，要么一并chmod。

还有，kaggle.json的权限检查在某些版本里是在读取时进行的，也就是说如果你的文件权限不对，报错会出现在你执行任何命令的时候，报错信息大致是Permissions for 'kaggle.json' should be 600。看到这句话不用怀疑人生，就是权限问题，一条chmod解决。

4.3 配置文件的读写逻辑与 config 命令

除了凭证，kaggle还有一些“运行时偏好”可以持久化，比如默认下载目录、默认竞赛。这些存在另一个文件里，通过kaggle config系列命令管理：

# 查看当前所有配置 kaggle config view # 设置默认下载目录 kaggle config set -n path -v ~/data/kaggle # 设置默认竞赛，之后下载可以不写 -c 参数 kaggle config set -n competition -v some-competition-slug # 取消某项设置 kaggle config unset -n competition

set -n path这个设置我个人非常推荐。默认情况下文件下载到当前工作目录，你在项目根目录敲命令，压缩包就散落在根目录里，很乱。设一个统一的下载目录之后，所有下载都归到一处，清理起来方便，也不容易误提交到 Git。

需要明白的是，config里存的这些是偏好，命令行参数可以覆盖它。比如你设了默认竞赛，但某次想下另一个，加-c other-slug就行，不用先unset。这个覆盖逻辑省了很多来回改配置的功夫。

5. 命令实战：把数据和任务搬进终端

前面都是铺垫，这一节是真正干活的部分。我把常用命令按场景分组，每条都标出我实际用下来觉得值得注意的参数。

5.1 数据集下载命令的参数取舍

最基础的一条：

kaggle datasets download -d owner/dataset-name

-d后面是数据集的完整标识，格式是“所有者/数据集名”，这个标识从数据集页面的 URL 里就能读到。下载下来是一个 zip 文件，文件名就是数据集名。

几个高频参数：

• --unzip：下载完自动解压。省一步，但要注意大文件解压耗时长，且会占双份磁盘空间。
• -p ./data/raw：指定输出目录，目录不存在会自动创建。
• -o：覆盖已存在的同名文件。不加这个，重复下载会报“文件已存在”然后跳过。
• -q：静默模式，不打印进度条。在脚本里很有用，避免日志被刷屏。

组合起来我最常用的写法是：

kaggle datasets download -d owner/dataset-name -p ./data/raw --unzip -o -q

关于--unzip的取舍，我的建议是：数据集体积小于 5 GB 且你确定要全量使用，就加；超过这个量，先不加，下载完用unzip -l看一眼内部结构，确认没有奇怪的嵌套目录再手动解压。我遇到过一次数据集内部是data/data/train.csv这种双层嵌套，自动解压后路径全乱，还得写脚本搬文件。

想先看看数据集里有哪些文件再决定下不下，用：

kaggle datasets files -d owner/dataset-name

这条命令只读元信息，不下文件，几秒钟出结果。养成先看再下的习惯，能省掉不少流量。

5.2 竞赛数据的特殊门槛：先接受规则

竞赛数据和公开数据集有个本质区别：必须先接受竞赛规则。这一步只能在网页上做，命令行做不了。没接受规则就去下载，会得到一个403 Forbidden，报错信息里不会明说“你没接受规则”，只会说权限不足，新手很容易误判成密钥问题。

正确的顺序是：先在浏览器里打开竞赛页面，找到规则入口，滚动到底部点接受。做完这一步，命令行的403就消失了。

接受规则之后的下载：

kaggle competitions download -c competition-slug -p ./data/comp

-c后面是竞赛标识，同样从 URL 里取。下载下来通常是一个包含train.csv、test.csv、sample_submission.csv的 zip 包。有些大型竞赛会拆成多个文件，用-f指定要下哪个：

kaggle competitions download -c competition-slug -f train.csv.zip

查看某个竞赛有哪些可下载文件：

kaggle competitions files -c competition-slug

5.3 提交与查询：把手工动作变成脚本

提交结果：

kaggle competitions submit -c competition-slug -f submission.csv -m "lgb baseline v1"

-m是提交说明，别偷懒不写。一天提交十几次之后，你在排行榜页面上看到一堆没备注的记录，根本分不清哪个对应哪次实验。我的习惯是备注里写清模型类型和关键参数，比如xgb depth6 lr0.05 seed42，回头复现最快。

提交之后查分数：

kaggle competitions submissions -c competition-slug

这条会列出你所有提交记录和对应分数。写进脚本里，配合grep和awk就能做“训练完自动提交并记录”的闭环：

#!/usr/bin/env bash set -e python train.py --out submission.csv kaggle competitions submit -c my-comp -f submission.csv -m "auto $(date +%m%d-%H%M)" kaggle competitions submissions -c my-comp | head -5

这个脚本我放在好几个项目里用，set -e保证训练失败时不会提交垃圾文件，date生成的备注能自动区分批次。有一点要注意：提交有频率限制，具体数值各竞赛不同，脚本里最好加个sleep或者简单的失败重试逻辑，别一口气把配额打光。

5.4 上传：datasets create / version 与 kernels push

上传数据集分三步。先生成元数据模板：

kaggle datasets init -p ./mydata

这会在./mydata下生成一个dataset-metadata.json，里面需要填标题、标识、描述、许可等字段。填好之后：

# 首次创建 kaggle datasets create -p ./mydata # 后续更新版本 kaggle datasets version -p ./mydata -m "add 2024 records"

-m是版本说明，必填。每次version会产生一个新版本，旧版本仍然可访问，用--version参数指定下载哪一版。

上传 notebook（平台上叫 kernel）的流程类似：

kaggle kernels init -p ./mykernel # 生成 kernel-metadata.json kaggle kernels push -p ./mykernel # 推送并运行 kaggle kernels status <username>/<kernel> # 查运行状态 kaggle kernels output <username>/<kernel> -p ./out # 拉取输出文件

这个组合的实用场景是“在云端跑长任务”。本地机器扛不住的大训练，推到平台上跑，跑完用kernels output把模型文件和日志拉回来。status命令返回的状态值有个坑：complete表示成功，error表示失败，但如果 metadata 里配了 GPU 而配额用完，状态会先卡在queued很久，不是报错。等不下去就去看网页端的运行日志，比盯着命令行有信息量。

6. 报错速查与排查思路

装和用的过程中，报错信息往往不够直白。这一节把我遇到过和帮别人解决过的典型问题整理成表，配合一套三步排查法。

6.1 高频报错速查表

6.2 三步定位法

报错一大堆的时候别慌，按这个顺序切分问题，能快速缩小范围。

第一步，判断是工具问题还是凭证问题。运行kaggle --version，能出版本号说明工具本身没问题，是执行阶段的事。运行kaggle competitions list -s "titanic"（纯只读），如果这条都失败，基本锁定在凭证或网络；如果这条成功但下载失败，问题在具体的数据集或竞赛权限上。

第二步，判断是权限还是路径。去网页端用同样的账号登录，手动点一次下载。网页能下、命令行不能下，大概率是本地配置问题（路径、权限、JSON 格式）。网页也下不了，那是账号或规则问题，跟命令无关。

第三步，看详细日志。加-v或者设置KAGGLE_LOGGING_LEVEL=DEBUG环境变量，能看到完整的请求 URL 和返回码。有了返回码，前面那张表就能直接对上号。

6.3 升级、降级与干净卸载

升级：

pip install --upgrade --no-cache-dir kaggle

加--no-cache-dir是为了避免缓存里的旧 wheel 干扰。升级完记得重新跑一次kaggle --version确认版本真的变了，有时候因为路径问题，升级装到了另一个环境，你用的还是老的。

降级到指定版本：

pip install "kaggle==1.5.16"

什么时候需要降级？我的经验是：升级后某个原本能用的命令突然报参数错误，说明新版改了接口。这时候先降回上一个能用的版本，把活干完，再去查变更说明。不要在生产脚本上跟新版本硬碰。

彻底卸载：

pip uninstall kaggle rm -rf ~/.kaggle # 凭证，谨慎，删了要重新生成 rm -rf ~/.kaggle-cli # 或者你自定义的环境目录

卸载时最容易漏的是凭证目录和配置目录。pip uninstall只删包，不删你的kaggle.json和 config 文件。如果是为了彻底清环境，这两处都得手动清。不过要注意，~/.kaggle里可能还存着你的 config 偏好，删之前想清楚。

再补一个小技巧：如果你在多个环境里都装过这个工具，卸载后which kaggle可能还能找到另一个环境里的版本，让人以为没卸干净。用type -a kaggle把所有命中路径列出来，对照着清理，比which直观。

7. 几个让我少走弯路的习惯

写到这里，核心的技术点基本覆盖完了。剩下几条是我自己长期用下来形成的习惯，不成体系，但每一条都对应过一次具体的麻烦。

第一条，把下载命令写进项目的Makefile或者scripts/pull_data.sh。别在终端里随手敲，敲完就忘了参数。写进文件里，队友 clone 下来看一眼就知道数据从哪来、怎么拉。项目 README 里只需要写一句make data，比长篇描述靠谱。

第二条，大数据集分文件下，不要一口气拉整包。先用kaggle datasets files看清单，挑需要的文件用-f单独下。几十 GB 的包下到 90% 断了，重来一遍的成本太高；单文件断了下单个，代价小得多。

第三条，凭证和项目彻底分离。我从不在项目目录里放kaggle.json，一律放家目录或者用KAGGLE_CONFIG_DIR指到项目外。项目目录是会被打包、分享、提交的，凭证放在里面迟早出事。这条规矩看起来简单，但真正养成习惯之后，你会对“什么东西不该进仓库”敏感很多。

第四条，提交备注当成实验日志写。前面提过，这里再强调一次。备注不是给平台看的，是给三个月后的自己看的。模型结构、关键超参、随机种子，能写就写。排行榜上翻记录的时候，一条清晰的备注能省掉重新翻代码的时间。

第五条，定期检查版本，但别追新。每隔一两个月跑一次pip install --upgrade kaggle看看有没有重要更新，但不要在赶 deadline 的前一天升级工具链。工具出问题的时机永远是最糟糕的那个，这条规律我验证过很多次。

最后分享一个我自己觉得挺有用的小扩展：把常用的几条命令包成一个 shell 函数，参数用位置变量传，日常操作就变成了kd comp、kd data、kd sub这种短命令。函数体放在.bashrc或者单独的aliases.sh里，换机器时把文件带走就行。工具本身的复杂度是固定的，但每天敲多少字符、记多少参数，是可以自己优化的。