youtube-publish 是做什么的？
YouTube Data API v3 上传器，无 SDK 依赖（使用纯 fetch，支持可恢复分块上传）。专为批量上传设计：默认私密上传，使用 sha256 记录防止重复发布，支持元数据检查、模拟运行和配额感知。
一次性设置（由用户完成，而非代理）
- Google Cloud Console：创建一个项目，启用 YouTube Data API v3，创建一个类型为 桌面应用 的 OAuth 客户端 ID。
- 将客户端提供给脚本，但不提交：
export YOUTUBE_CLIENT_ID=... YOUTUBE_CLIENT_SECRET=...（或将下载的 JSON 文件放在仓库外部，并通过--client-secrets参数指定）。 - 一次性授权频道：
打开同意页面，在 127.0.0.1 上捕获重定向（PKCE + state 检查），以模式 600 存储刷新令牌。令牌永远不会被打印。node scripts/auth.mjs --token-file .youtube-token.json
工作流程
# 1. 模拟运行：验证元数据，对文件进行哈希，显示跳过/上传计划以及配额成本
node scripts/upload.mjs --jobs jobs.json --dry-run
# 2. 上传（默认为私密）
node scripts/upload.mjs --jobs jobs.json --token-file .youtube-token.json
# 单个文件
node scripts/upload.mjs --file publish/short.mp4 --title "如何自动化我的编辑" --tags shorts,自动化 --privacy unlisted
jobs.json：
[
{ "file": "publish/short-01.mp4", "title": "...", "description": "...", "tags": ["shorts"], "privacy": "private" },
{ "file": "publish/short-02.mp4", "title": "...", "privacy": "private", "publishAt": "2026-11-01T17:00:00Z" }
]
相对 file 路径根据作业文件所在的文件夹解析。
规则
- 只上传已通过
render-qc且经用户批准的文件。 - 默认隐私设置为
private。除非用户明确要求并且你传递了--allow-public参数，否则拒绝public。计划发布的视频（publishAt）必须为private；YouTube 会在计划时间将其转为公开。 - 始终先进行
--dry-run并向用户显示计划。 - 绝不打印、记录或提交令牌、客户端密钥、
.env*文件或记录。仓库的.gitignore已经涵盖了*token*.json、*credentials*.json、*client_secret*.json、.env*和*ledger*.json。 - 记录（
.youtube-upload-ledger.json）是已发布内容的权威来源。每次上传后都会保存它。不要删除它以“重试”；仅在用户确实想要第二个副本时使用--force-duplicate。 - 配额：默认情况下，一个项目每天获得 10,000 单位，历史上一次上传消耗 1,600 单位（约每天 6 次上传）。
--max-uploads（默认为 6）可防止一次运行消耗完配额；--units-per-upload可在 Google 更改成本时调整估算值。遇到quotaExceeded时，运行会停止，剩余作业可在第二天重新运行（记录会跳过已完成的作业）。 - 标题：不能有占位符（TODO、untitled、
{{...}}），最多 100 个字符，不能包含<或>。标签总长度最多 500 个字符。lint 会强制执行这些规则。 - 未经验证的 API 项目可能会强制上传为私密，直到 Google 审计应用；如果每次上传都返回私密状态，请告知用户。
验证
每个结果都有一个 videoId（当视频仍为私密时，可以打开 https://youtu.be/<id>）或一个 skipped 原因。node scripts/upload.mjs --check-auth 在不进行上传的情况下测试凭据。