youtube-publish 是做什麼的？
無需 SDK 依賴（使用純 fetch、可續傳分塊上傳）的 YouTube Data API v3 上傳工具。專為批次上傳設計：預設私人權限、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 + 狀態檢查），以模式 600 儲存重新整理權杖。權杖永遠不會被列印出來。node scripts/auth.mjs --token-file .youtube-token.json
工作流程
# 1. 乾執行：驗證中繼資料、雜湊檔案、顯示略過/上傳計劃與配額成本
node scripts/upload.mjs --jobs jobs.json --dry-run
# 2. 上傳（預設私人）
ode scripts/upload.mjs --jobs jobs.json --token-file .youtube-token.json
# 單一檔案
node scripts/upload.mjs --file publish/short.mp4 --title "How I automated my edits" --tags shorts,automation --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 個字元。檢查機制會強制執行此規則。 - 未經驗證的 API 專案可能會強制將上傳設為私人，直到 Google 審核應用程式為止；如果每次上傳都變回私人，請告知使用者。
驗證
每個結果都有一個 videoId（在影片仍為私人時開啟 https://youtu.be/<id>）或一個 skipped 原因。node scripts/upload.mjs --check-auth 可在不上傳的情況下測試憑證。