Spec Kit 鉴权问题与本地化解决方案

一、问题背景
Spec Kit 是 GitHub 开源的 Spec-Driven Development 工具，用 specify init 初始化项目时会从 GitHub API 拉取最新模板。在国内或企业网络环境下，常会遇到：
401 Unauthorized：GitHub API returned status 401 for https://api.github.com/repos/github/spec-kit/releases/latest
配置了 Token 仍失败：设置了 GITHUB_TOKEN 或 --github-token 依然报 401
Windows 编码错误：UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’
二、原因分析
2.1 401 的常见原因
原因 说明
Token 无效或过期 环境变量中的 Token 已失效，仍被发送，GitHub 返回 401
网络/代理限制 国内或企业网络无法稳定访问 GitHub API
Token 传递方式错误 使用 .env 或错误格式，导致未正确传递
根据 GitHub https://github.com/github/spec-kit/issues/378，若环境变量 GITHUB_TOKEN 或 GH_TOKEN 存在但 Token 无效，Spec Kit 会带上该 Token 请求 API，反而会触发 401。取消设置这些变量，改用匿名请求，有时可以成功。
2.2 Token 配置无效
https://github.com/github/spec-kit/issues/1076 中，用户将 Token 写在 .env 中仍失败，改为在命令行中直接传入后成功：

错误：依赖 .env 或环境变量specify init . --github-token GITHUB_TOKEN # 传的是字面量，不是真实 Token# 正确：直接传入真实 Tokenspecify init . --ai claude --github-token=ghp_你的实际token

三、常规排查步骤
在尝试本地化方案前，可先按下面顺序排查：
步骤 1：清空 Token 后重试（匿名访问）

PowerShell$env:GITHUB_TOKEN =n u l l nullnullenv:GH_TOKEN = $nullspecify init . --ai claude

Bashunset GITHUB_TOKEN GH_TOKENspecify init . --ai claude

步骤 2：正确传入 Token
specify init . --ai claude --github-token=ghp_你的真实token
步骤 3：配置代理（国内环境）
e n v : H T T P P R O X Y = " h t t p : / / 127.0.0.1 : 7890 " env:HTTP_PROXY = "http://127.0.0.1:7890"env:HTTPP​ROXY="http://127.0.0.1:7890"env:HTTPS_PROXY = "http://127.0.0.1:7890"specify init . --ai claude
步骤 4：企业网络 / SSL 问题
specify init . --ai claude --skip-tls
若以上都无效，建议采用下面的本地化方案。
四、本地化解决方案（推荐）
思路：不再依赖 GitHub API，从本地 spec-kit 源码构建模板 zip，用 --local-template 初始化。
4.1 克隆 Spec Kit 源码
git clone https://github.com/github/spec-kit.git spec-kit-tempcd spec-kit-temp
4.2 构建本地模板
Spec Kit 的 create-release-packages.sh 会生成模板目录，但在 Windows 上常因缺少 zip 命令而失败。可先用脚本生成目录，再用 Python 打 zip：

1. 生成模板目录（会在 zip 步骤失败，但目录已生成）bash .github/workflows/scripts/create-release-packages.sh v0.3.2# 2. 用 Python 生成 zip（Windows 无 zip 时使用）python -c “import zipfilefrom pathlib import Pathbase = Path(‘.genreleases/sdd-claude-package-sh’)zip_path = Path(‘.genreleases/spec-kit-template-claude-ps-v0.3.2.zip’)with zipfile.ZipFile(zip_path, ‘w’, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(‘*’): if f.is_file(): zf.write(f, f.relative_to(base))print(‘Created:’, zip_path.resolve())”

4.3 使用本地模板初始化

在当前目录初始化uv run --project f:\path\to\spec-kit-temp specify init . --ai claude \ --local-template f:\path\to\spec-kit-temp.genreleases\spec-kit-template-claude-ps-v0.3.2.zip \ --here --force

4.4 一键构建脚本
可将上述步骤写成 build-local-template.sh，方便重复使用：
#!/usr/bin/env bashset -ecd “$(dirname “0 " ) " B A S E = " . g e n r e l e a s e s / s d d − c l a u d e − p a c k a g e − s h " i f [ [ ! − d " 0")"BASE=".genreleases/sdd-claude-package-sh"if [[ ! -d "0")"BASE=".genreleases/sdd−claude−package−sh"if[[!−d"BASE” ]]; then echo “Building template package…” bash .github/workflows/scripts/create-release-packages.sh v0.3.2fiif [[ -d “$BASE” ]]; then echo “Creating zip archive…” python -c 'import zipfilefrom pathlib import Pathbase = Path(”.genreleases/sdd-claude-package-sh")zip_path = Path(“.genreleases/spec-kit-template-claude-ps-v0.3.2.zip”)with zipfile.ZipFile(zip_path, “w”, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(“*”): if f.is_file(): zf.write(f, f.relative_to(base))print(“Created:”, zip_path.resolve())’ echo "Done. Use: specify init . --ai claude --local-template $(pwd)/.genreleases/spec-kit-template-claude-ps-v0.3.2.zip --here --force"else echo “Error: Package dir not found.” exit 1fi
保存后执行：
bash build-local-template.sh
五、关于 --local-template 选项
–local-template 并非 Spec Kit 官方默认支持，需自行修改源码。若使用官方未修改版本，可：
在能访问 GitHub 的环境（如云服务器、VPN）完成 specify init，再把生成的项目拷贝到本地；
或向 spec-kit 仓库 提交 Issue/PR，请求增加离线/本地模板支持。
六、Windows 编码问题
若出现 UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’，多为错误信息中的 Unicode 字符（如 •）在 GBK 下无法编码。可尝试：

切换控制台为 UTF-8chcp 65001

或设置环境变量：
$env:PYTHONIOENCODING = “utf-8”
若使用修改过的 Spec Kit 源码，可将错误文案中的 • 替换为 -，避免 GBK 编码问题。
七、总结
场景 建议方案
能访问 GitHub 清空无效 Token 或正确传入 Token
国内/企业网络 配置代理或使用本地模板
完全离线 克隆 spec-kit，本地构建 zip，用 --local-template 初始化
Windows 编码报错 chcp 65001 或修改错误信息中的 Unicode 字符
希望本文能帮助遇到类似问题的开发者顺利完成 Spec Kit 的本地化使用。
参考资料
https://github.com/github/spec-kit
https://github.com/github/spec-kit/issues/378 - 401 with invalid token
https://github.com/github/spec-kit/issues/1076 - Token in .env not working
https://github.com/github/spec-kit/issues/273 - 403 rate limit / 国内代理配置