Claude Code 实战指南：从零构建一个 AI 编程街机厅

看到 “Show HN” 出现，通常意味着一个新奇项目被摆到技术社区首页接受围观，而 “Claude Code Arcade” 这个组合，核心思路很有意思：与其让 Claude Code 只帮你改业务代码，不如把它丢进一个游戏项目集里，让它一口气产出若干个小游戏、交互 Demo，形成一个可随时运行的 “街机厅”。这类项目也是检验 AI 编程工具下限和上限的好方式——如果连贪吃蛇、打砖块这种需要状态管理、碰撞检测、交互反馈的小游戏都能稳定产出，那日常 CRUD、脚本编写、组件开发自然不在话下。

本文不会只贴一个仓库链接，而是把它拆成一个可落地的实践教程：先从 Claude Code 环境安装说起，再聊怎么设计 “Arcade 式” 游戏项目，接着给出完整的项目结构和可运行的代码示例，最后把常见报错、Token 优化技巧、工程化建议一并整理出来。不管你是刚听说 Claude Code 的新手，还是已经用它写过一段时间代码的开发者，都可以照着做一遍。

1. 背景与核心概念

1.1 Claude Code 是什么

Claude Code 是 Anthropic 官方推出的终端编程代理工具。它不是一个普通的聊天窗口，而是直接运行在你的命令行环境中，能够读写项目文件、执行命令、运行测试、查找报错，并根据你给出的任务目标自主完成一系列开发操作。

例如你想给项目增加一个“从 CSV 导入用户”的功能，普通聊天机器人只能给你一段参考代码，而 Claude Code 可能直接帮你完成以下步骤：

1. 阅读项目目录结构，定位现有数据层代码。
2. 添加 CSV 解析依赖。
3. 编写导入服务与对外接口。
4. 在当前环境执行测试命令，观察是否通过。
5. 根据失败信息继续修改，直到测试通过。

这意味着，Claude Code 更像一个“驻场 AI 程序员”，而不是 “你问一句、它答一段” 的在线问答工具。

1.2 Arcade 项目的典型玩法

Arcade 的本意是“街机厅”，放在 Claude Code 语境中，通常指代这么一类项目：利用 Claude Code 的对话式编程能力，在短时间内生成一组相对独立的小游戏，并把它们组织到一个统一入口页面中。

比较常见的形态有：

• 一个单页面游戏合集，包含贪吃蛇、扫雷、2048、记忆翻牌等小游戏。
• 每个游戏独立成一个 HTML 文件，双击即可运行。
• 用 Claude Code 完成初始代码后，继续通过对话提需求，例如“把蛇改成绿色渐变”“增加移动端触屏支持”“给翻牌游戏增加连击特效”。
• 在迭代过程中检验 Claude Code 对需求变更、代码修改、回归测试等真实开发场景的处理能力。

这类项目非常适合用来实践 Claude Code，原因有三个：

1. 小游戏功能边界清晰，方便拆分任务。
2. 图形和交互逻辑直观，修改后肉眼可见。
3. 涉及状态变化、事件循环、定时器、DOM 操作等常规前端概念，覆盖面广。

1.3 为什么值得动手做一遍

很多开发者刚开始使用 Claude Code 时，只会让它改一行配置、写一个函数，并没有体会到它作为“项目级开发代理”的完整能力。通过一个 Arcade 项目，你可以系统性地验证以下几点：

• 它能否独立完成一个从零到一的小项目？
• 它能否在已有代码上准确修改功能，而不是每次推倒重写？
• 它能否通过运行测试或打开浏览器等方式自查结果？
• 遇到编译错误、逻辑错误时，它能否自己排查并修复？
• 任务的 token 消耗是否可控？

这些问题只有亲手跑完一个完整项目才有答案。

2. 环境准备与版本说明

2.1 基础运行环境

Claude Code 以 npm 包形式分发，主要运行在命令行环境中。不同操作系统的安装步骤略有差异，但大前提基本一致：

你需要一个能正常使用 npm 的环境。由于 Claude Code 是终端工具，推荐使用 macOS 或 Linux 自带终端，Windows 用户建议使用 PowerShell 5.1+ 或 Windows Terminal。

版本说明：

Node.js: 建议使用 18.x 或更高版本 npm: 建议使用 9.x 或更高版本 Claude Code: 安装最新版本即可

具体版本要求变化较快，建议以官方安装说明为准。安装前可以在终端中检查基础环境：

node -v npm -v

如果两个命令都能正常输出版本号，说明基础环境已经满足。

2.2 安装 Claude Code

在国内开发者群体中，安装 Claude Code 已经有不少教程和踩坑记录，但无论你看到的是什么版本，底层流程基本一致。

安装命令：

npm install -g @anthropic-ai/claude-code

如果遇到权限问题，Linux 或 macOS 可以加上 sudo：

sudo npm install -g @anthropic-ai/claude-code

如果你的 npm 全局目录权限配置正确，也可以不加 sudo。

安装完成后，验证是否成功：

claude --version

如果能看到版本号，说明命令行工具已经正确安装。

2.3 登录与模型访问

安装完成后，首次运行需要登录或配置模型访问权限：

claude

首次启动通常会自动打开浏览器，完成账号授权流程。授权成功后，Claude Code 就可以代表你发起模型请求了。

这里有一个重要的注意点：如果你所在的组织或订阅计划没有开放 Claude Code 访问权限，你可能会遇到类似 “Your organization has disabled Claude subscription access for Claude Code” 的提示。遇到这种情况，要检查的是：

• 当前使用的订阅计划是否包含 Claude Code 权限。
• 账号是否为组织管理员限制。
• 是否需要在 API 平台单独开通访问。

另外，Claude Code 也支持通过 Anthropic API 密钥方式运行。如果你使用 API 方式，需要配置环境变量：

export ANTHROPIC_API_KEY="你的_API_KEY"

注意：不要把 API Key 写进项目中的配置文件，更不要提交到 Git 仓库。

2.4 在 VSCode 中使用 Claude Code

不少开发者习惯在 VSCode 中开发，Claude Code 也可以集成进 VSCode 的终端中。

如果你希望在一个可视化环境中使用，可以这样做：

1. 打开 VSCode。
2. 按快捷键Ctrl + ~打开内置终端。
3. 在终端中运行claude。
4. 直接在当前项目目录中进行对话式编程。

此时 Claude Code 能读取到当前 VSCode 打开的项目目录，修改文件、创建目录都会直接反映到 VSCode 的文件树中。

本质上，Claude Code 是一个命令行工具，和 VSCode 是否安装没有硬性依赖关系。如果你想使用 Anthropic 官方的 VSCode 扩展，需要自己去扩展市场搜索相关插件并阅读安装说明，这里特别提醒注意扩展来源，防止安装到第三方非官方插件导致密钥泄露。

2.5 项目结构约定

本文的 Arcade 示例会采用以下目录结构：

claude-code-arcade/ ├── index.html ├── games/ │ ├── snake/ │ │ ├── index.html │ │ ├── style.css │ │ └── game.js │ ├── memory/ │ │ ├── index.html │ │ ├── style.css │ │ └── game.js │ └── breakout/ │ ├── index.html │ ├── style.css │ └── game.js └── docs/ └── chatlog.md

其中docs/chatlog.md用来记录你与 Claude Code 的完整对话记录，方便事后退溯与复盘。

3. Claude Code 核心配置与使用思路

3.1 会话中的任务式交流

Claude Code 和普通聊天机器人最大的区别在于，它不会只“回答”你，它会“执行”。在 Arcade 项目中，你可以直接输入任务类 Prompt，例如：

请在我的项目根目录下创建 games/snake 目录，并实现一个贪吃蛇游戏。 要求： 1. 使用原生 HTML + CSS + JavaScript，不依赖任何第三方库。 2. 游戏区域为 400x400 的 canvas。 3. 支持键盘方向键控制。 4. 吃到食物后蛇身增长，分数加 10。 5. 游戏结束后显示“Game Over”和最终分数，并支持回车重新开始。

这时，Claude Code 会自动读取你的项目结构，然后创建对应目录和文件。完成编写后，它可能会提示你打开浏览器验证效果，或建议你运行一个本地静态服务器。

3.2 保存任务配置的 CLAUDE.md

在 Claude Code 中，CLAUDE.md 文件用于描述项目背景和编码约定。合理配置这个文件可以让多轮对话、不同会话之间的上下文保持一致，不必每次重复强调需求。

建议在claude-code-arcade项目中创建CLAUDE.md：

# Claude Code Arcade 项目说明 你正在一个游戏合集项目中工作，项目目标是使用原生 HTML/CSS/JavaScript 实现多款小型街机游戏。 ## 项目结构 - index.html: 游戏大厅入口 - games/: 每个游戏一个目录，目录名为小写英文单词 ## 编码规范 - 不使用任何第三方框架或构建工具 - 每个游戏必须包含 index.html、style.css、game.js 三个文件 - JavaScript 使用 ES6 语法 - 所有注释使用中文 - 游戏主循环使用 requestAnimationFrame 或 setInterval - 用户界面文字使用中文 ## 完成标准 - 必须在浏览器中可运行 - 必须支持键盘操作 - 游戏失败后必须提供重新开始方式

写好这个文件后，每次启动 Claude Code 时，它都会自动读取项目根目录的 CLAUDE.md，从而更快理解你的项目背景。这意味着你不用在每一轮对话中都重复“不要用框架”“使用原生 JavaScript”等要求。

3.3 Skills 与自定义指令

Claude Code 的 Skills 是给模型提供的一组可复用操作能力，类似给 IDE 添加代码片段或宏。你可以配置一个 Skill，让 Claude Code 在新增游戏时按固定流程执行。

例如你可以在项目中创建.claude/skills/new-game/SKILL.md文件：

# 新增游戏 Skill 当用户输入“新增游戏 + 游戏名”时，按以下流程执行： 1. 读取 CLAUDE.md 确认游戏命名规范和目录结构。 2. 在当前项目的 games 目录下创建以游戏名命名的子目录。 3. 依次创建 index.html、style.css、game.js 三个文件。 4. 使用原生 JavaScript 编写游戏逻辑。 5. 确保 index.html 中引用同目录下的 style.css 与 game.js。 6. 更新根目录 index.html 的游戏大厅入口，加入新游戏卡片。

这种操作的好处是：后续你再提出“新增一个扫雷游戏”时，只要任务明确、模型具备对应 Skills，它就能按照预设工序完成任务，减少跑偏概率。

不过需要说明的是，不同时期 Claude Code 对 Skills 的目录规范和加载方式可能有调整。如果你使用的版本不生效，可以检查官方文档中关于 Skills 的最新说明。

3.4 设置默认回复语言

Claude Code 默认可能使用英文回复。如果你希望它始终使用中文，可以在启动后的对话中直接说明：

请始终使用中文回复，包括代码注释和提交说明。

Claude Code 有一定的上下文记忆能力，在同一会话内通常可以保持这个语言设置。如果你希望每次开始新会话都自动生效，可以把“使用中文回复”写到 CLAUDE.md 中。

3.5 会话历史的保存与查询

开发 Arcade 这种多轮迭代项目时，会话历史非常宝贵。它记录了需求的产生、代码的调整、bug 的修复过程。

当你启动 Claude Code 时，正常情况下会话历史会被自动保存。你可以直接在会话中问它：

我们上一轮实现的 2048 游戏的逻辑是什么？

或者，你想查看某个历史任务的关键决策，也可以直接问：

把当前会话中对蛇的移动逻辑的关键修改过程整理到 docs/chatlog.md 中。

如果你发现自己无法找到历史会话，优先检查 Claude Code 的配置文件和数据目录权限，而不是盲目重装。

3.6 自定义 settings.json

Claude Code 的用户级配置通常保存在settings.json中。它用于存放一些全局偏好设置，例如：

{ "permissions": { "allow": [ "Read", "Edit", "Bash(npm run *)" ] }, "model": "claude-sonnet-4-20250514" }

这里需要特别提醒：具体可配置项和模型标识因版本不同而存在差异。很多网上教程为了让 Claude Code 接入第三方模型，会指导用户修改 settings.json，但如果你把模型名写错，就可能看到类似：

"deepseek-v4-flash" is not a model this version of Claude Code recognizes

这种提示说明当前版本的 Claude Code 并不认识你填写的模型标识，而不是代码本身出了问题。

遇到这类问题后，首先应当确认你使用的模型服务商、模型名称和当前 Claude Code 版本的兼容性，不要盲目照抄热门帖子里的配置。毕竟不同时期的模型市场变化太大，教程只具有思路参考价值。

4. 用 Claude Code 实战搭建一个 Arcade 游戏集合

4.1 明确第一个版本范围

在真正开始写代码之前，先做一次“任务收敛”。不要一次性对 Claude Code 说“给我做十个游戏”，那样容易失控，也会消耗大量 Token。

建议第一个版本的完成标准如下：

• 游戏大厅index.html可以打开。
• 大厅里展示三个游戏卡片，分别是贪吃蛇、记忆翻牌、打砖块。
• 点击卡片后打开对应的游戏页面。
• 每个游戏可正常开始、游玩、结束。
• 游戏结束后有重新开始入口。

4.2 初始化项目目录

在终端中创建项目目录并进入：

mkdir claude-code-arcade cd claude-code-arcade

然后启动 Claude Code：

claude

接下来，给 Claude Code 下达第一个任务：

请先阅读当前目录。这是一个空目录，我要在这里构建一个 Arcade 游戏合集项目。 第一步，请创建如下文件： 1. index.html：游戏大厅，标题为“Claude Code Arcade”，包含贪吃蛇、记忆翻牌、打砖块三个入口卡片。 2. CLAUDE.md：说明这是一个游戏合集项目，使用原生 HTML/CSS/JavaScript，不使用框架，所有页面中文显示。

4.3 逐步生成游戏代码

第一个版本可以先让 Claude Code 完成贪吃蛇游戏。

使用原生 JavaScript 实现贪吃蛇游戏。 游戏页面文件路径为 games/snake/index.html、games/snake/style.css、games/snake/game.js。 要求如下： 1. 游戏区域是一个 400x400 的 canvas，绘制 20x20 网格。 2. 蛇初始长度为 3，初始方向向右。 3. 每 150ms 更新一次蛇的位置。 4. 键盘方向键控制蛇的移动方向，不允许原地掉头。 5. 食物随机生成在网格内。 6. 蛇吃到食物后长度加 1，分数加 10。 7. 蛇撞到边界或自身时游戏结束，弹层显示最终得分，回车键重新开始。 8. 页面顶部显示当前分数。

Claude Code 会按照这个要求生成对应代码。因为任务描述非常具体，生成结果通常比较稳定。

下面是一个符合上述要求的贪吃蛇核心代码示例，供你理解任务描述的落地效果。

文件路径：games/snake/game.js

const canvas = document.getElementById('gameCanvas'); const ctx = canvas.getContext('2d'); const scoreElement = document.getElementById('score'); const GRID_SIZE = 20; const CELL_SIZE = canvas.width / GRID_SIZE; let snake = []; let direction = { x: 1, y: 0 }; let nextDirection = { x: 1, y: 0 }; let food = {}; let score = 0; let gameOver = false; let gameInterval = null; function initGame() { snake = [ { x: 7, y: 10 }, { x: 6, y: 10 }, { x: 5, y: 10 } ]; direction = { x: 1, y: 0 }; nextDirection = { x: 1, y: 0 }; score = 0; gameOver = false; scoreElement.textContent = '0'; spawnFood(); if (gameInterval) clearInterval(gameInterval); gameInterval = setInterval(gameLoop, 150); } function spawnFood() { while (true) { const x = Math.floor(Math.random() * GRID_SIZE); const y = Math.floor(Math.random() * GRID_SIZE); if (!snake.some(segment => segment.x === x && segment.y === y)) { food = { x, y }; return; } } } function gameLoop() { direction = nextDirection; const head = { x: snake[0].x + direction.x, y: snake[0].y + direction.y }; if ( head.x < 0 || head.x >= GRID_SIZE || head.y < 0 || head.y >= GRID_SIZE || snake.some(segment => segment.x === head.x && segment.y === head.y) ) { endGame(); return; } snake.unshift(head); if (head.x === food.x && head.y === food.y) { score += 10; scoreElement.textContent = score; spawnFood(); } else { snake.pop(); } drawGame(); } function endGame() { clearInterval(gameInterval); gameOver = true; alert('游戏结束！得分：' + score); initGame(); } function drawGame() { ctx.fillStyle = '#1a1a2e'; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.fillStyle = '#e94560'; ctx.fillRect( food.x * CELL_SIZE, food.y * CELL_SIZE, CELL_SIZE, CELL_SIZE ); snake.forEach((segment, index) => { if (index === 0) { ctx.fillStyle = '#16c79a'; } else { ctx.fillStyle = '#11999e'; } ctx.fillRect( segment.x * CELL_SIZE, segment.y * CELL_SIZE, CELL_SIZE - 1, CELL_SIZE - 1 ); }); } document.addEventListener('keydown', event => { if (gameOver) return; const keyMap = { 'ArrowUp': { x: 0, y: -1 }, 'ArrowDown': { x: 0, y: 1 }, 'ArrowLeft': { x: -1, y: 0 }, 'ArrowRight': { x: 1, y: 0 } }; const newDirection = keyMap[event.key]; if (!newDirection) return; event.preventDefault(); if ( newDirection.x !== -direction.x || newDirection.y !== -direction.y ) { nextDirection = newDirection; } }); initGame();

文件路径：games/snake/index.html

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>贪吃蛇 - Claude Code Arcade</title> <link rel="stylesheet" href="style.css"> </head> <body> <h1>贪吃蛇</h1> <div class="score-board"> 当前分数：<span id="score">0</span> </div> <canvas id="gameCanvas" width="400" height="400"></canvas> <script src="game.js"></script> </body> </html>

文件路径：games/snake/style.css

body { margin: 0; padding: 20px; background: #0f0f23; color: #ffffff; text-align: center; font-family: Arial, sans-serif; } canvas { background: #1a1a2e; border: 2px solid #16c79a; display: block; margin: 20px auto; } .score-board { font-size: 20px; }

这是贪吃蛇游戏最基础的实现版本，如果你把代码原封不动保存到对应文件中，打开 HTML 页面即可运行。注意，这段代码只是示例中的核心逻辑，实际项目中由 Claude Code 生成的代码可能有变量名和样式上的差异，这很正常。

4.4 继续生成第二个游戏：记忆翻牌

贪吃蛇验证通过后，第二个任务可以选择一个对 DOM 操作要求更高的游戏，比如记忆翻牌。

在 games/memory 下实现记忆翻牌游戏，文件名依旧使用 index.html、style.css、game.js。 要求： 1. 使用 4x4 网格，共 8 对卡片。 2. 卡片正面显示 emoji 或数字符号。 3. 点击卡片实现翻牌效果，翻开两张后可判断是否匹配。 4. 匹配成功时保持正面显示，匹配失败时 0.8 秒后自动翻回。 5. 游戏过程中统计翻牌次数。 6. 所有卡片都匹配成功后，显示通关提示，并提供再次游戏按钮。

记忆翻牌涉及卡片数据管理、翻转状态、点击事件、延时器处理等多个逻辑点，比贪吃蛇更能验证 Claude Code 的完整实现能力。如果它生成的代码出现“点击过快导致连续翻开三张”这种问题，你可以继续追问让 Claude Code 自己修复。

这类 bug 很适合做代码评审测试：

我发现连点卡片时会出现翻开三张以上的情况，请你检查并限制点击频率：在尚未翻开第二张并完成匹配判断前，禁止继续点击其他卡片。

4.5 实现游戏大厅统一入口

三个游戏都完成后，最后让 Claude Code 更新游戏大厅index.html。

理想情况下，它应该生成类似下面的入口页面：

文件路径：index.html

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Claude Code Arcade</title> <style> body { margin: 0; min-height: 100vh; background: linear-gradient(135deg, #0f0f23, #1a1a2e); color: #ffffff; display: flex; flex-direction: column; align-items: center; justify-content: center; font-family: Arial, sans-serif; } .card-list { display: flex; gap: 20px; flex-wrap: wrap; justify-content: center; margin-top: 40px; } .game-card { width: 180px; padding: 30px 15px; background: rgba(255, 255, 255, 0.08); border: 1px solid rgba(255, 255, 255, 0.2); border-radius: 16px; text-align: center; text-decoration: none; color: #ffffff; transition: all 0.3s; } .game-card:hover { transform: translateY(-6px); border-color: #16c79a; box-shadow: 0 10px 25px rgba(22, 199, 154, 0.2); } </style> </head> <body> <h1>Claude Code Arcade</h1> <p>选择一款游戏开始挑战</p> <div class="card-list"> <a class="game-card" href="games/snake/index.html"> <h2>贪吃蛇</h2> <p>经典蛇类玩法</p> </a> <a class="game-card" href="games/memory/index.html"> <h2>记忆翻牌</h2> <p>考验你的记忆力</p> </a> <a class="game-card" href="games/breakout/index.html"> <h2>打砖块</h2> <p>弹球消砖块</p> </a> </div> </body> </html>

4.6 运行验证

所有游戏都是纯静态前端页面，没有构建步骤。你可以直接用浏览器打开index.html，也可以启动一个本地静态服务器，更贴近生产访问方式：

在项目根目录运行：

npx serve .

或者使用 Python：

python3 -m http.server 8080

终端会输出一个本地地址，例如：

Serving HTTP on :: http://0.0.0.0:8080

此时打开浏览器访问http://localhost:8080，就能看到游戏大厅。

建议你在浏览器中把每个游戏都实际操作一遍，重点是验证边界场景：

• 贪吃蛇撞墙时是否正常结束。
• 贪吃蛇连续快速按两次方向键是否会发生原地掉头。
• 记忆翻牌连续点击三张卡片时状态是否正确。
• 打砖块清除全部砖块后是否判定过关。

如果发现这类问题，直接回到终端，把具体现象告诉 Claude Code：

贪吃蛇游戏中，我快速按下“上”和“左”方向键，蛇会发生原地掉头导致游戏结束。请修复这个问题。

这是 Claude Code 完整开发闭环中最有价值的一步：发现问题、描述现象、让它自主修复、再次验证。

4.7 一个更实用的任务式扩展

游戏版本稳定后，你还可以继续测试 Claude Code 的深层能力。比如：

我想给 Arcade 项目增加“排行榜”功能。在 localStorage 中记录每个游戏的最高分和最近一次得分。 请在游戏大厅 index.html 中新增“本地排行”区域，显示每个游戏的最高分，并在每个游戏结束时更新 localStorage。 不要修改每个游戏的现有交互逻辑，只做分数记录相关的扩展。

这个任务考察的是 Claude Code 在多个文件之间保持一致性的能力。它需要读取所有游戏代码、理解游戏结束位置的逻辑、提炼分数数据、同步修改多个文件，而不是像第一次生成游戏那样仅仅是写独立代码。

这类任务最适合用来判断 Claude Code 是否真的理解项目结构，还是只是机械地帮你写函数。

5. 常见问题与排查思路

5.1 高频错误汇总表

下面整理了一些 Claude Code 使用中比较容易遇到的现象、原因和解决思路，供你快速对照。

5.2 Windows PowerShell 安装报错

Windows 用户在运行 npm 安装时，最常见的两类问题是权限不足和脚本执行策略限制。

如果你遇到类似错误，可以先用管理员身份打开 PowerShell，然后检查 npm 根目录：

npm prefix -g

然后确认该目录是否在系统环境变量 PATH 中。检查 PATH 时使用 PowerShell 命令：

$env:Path -split ';'

找到 npm 全局目录后，将其添加到 PATH 中。Script 执行策略问题如果导致错误，可以在管理员 PowerShell 中查看当前策略，但我不建议你为了一个工具把执行策略改成“不受限制”，更安全的做法是带上当前用户作用域调整后再复原。

5.3 返回内容乱码

Claude Code 在 Windows 终端中出现乱码，绝大多数情况是编码问题。建议把 Windows Terminal 和 VSCode 终端默认编码设置为 UTF-8。

在 VSCode 中，可以打开设置搜索terminal.integrated.defaultProfile.windows，并检查配置文件编码格式。把 VSCode 底部状态栏中的文件编码切换为 UTF-8，通常可以解决大部分中文乱码。

5.4 模型接入报错

网上有不少教程教你修改 settings.json，让 Claude Code 接入 DeepSeek、Ollama 本地模型或 ChatGPT 接口。这种思路的本质是利用 Claude Code 的模型接口兼容性连接不同的模型服务。

但这里存在非常大的版本差异问题。当你看到类似：

"deepseek-v4-flash" is not a model this version of Claude Code recognizes

说明你使用的 Claude Code 版本无法识别你配置的模型标识。

排查顺序如下：

1. 确认第三方模型服务商提供的模型名称是否真实存在。
2. 确认 Claude Code 版本是否支持第三方模型接入。
3. 检查需要配合的代理组件或环境变量是否配置成功。
4. 尝试升级或降级 Claude Code 版本。

尤其是用 Claude Code + Ollama 跑本地模型这种玩法，不同版本的 Claude Code 对 Ollama 的适配程度不同，遇到怪问题不要急着怀疑模型能力，先检查版本匹配情况。

5.5 保存历史与全局配置失败

如果你发现对话历史没有被记录，优先排查配置目录是否可写。在 Linux 中常见的原因是全局目录的权限不足，导致 Claude Code 无法创建日志文件。

你可以先搞清楚 Claude Code 使用了哪些本地配置目录，然后确认当前用户对这些目录拥有读写权限。这里注意，不同版本的 Claude Code 配置文件位置可能不一样，建议查看官方文档或让 Claude Code 直接告诉你：

请告诉我你的配置保存在哪个目录？顺便检查一下当前用户是否对这些目录有读写权限。

这样的排查方式比自己盲列配置文件路径更高效。

6. 最佳实践与工程建议

6.1 把任务拆小，而不是一次说完

很多新手使用 Claude Code 时喜欢一次输入很长的需求，比如“请帮我做一个游戏大厅，里面包含十个经典游戏，还要有排行榜、音效、移动端适配和暗黑模式”。

这种大而全的任务容易导致两个问题：

1. 生成代码量过大，token 消耗高，中途容易出现上下文偏移。
2. 需求中不同功能之间存在依赖关系，一次性完成的代码难以局部修改。

我建议的拆分方式是按“用户可感知的功能增量”拆分，每次只完成一个可运行的小模块。先让贪吃蛇能吃到食物，再考虑加音效；先把记忆翻牌的基本匹配逻辑做通，再考虑加计时器。

6.2 写 CLAUDE.md 而不是口头提醒

CLAUDE.md 是项目级的长期记忆，每次会话在项目根目录启动时，它都会被读取。把不会经常变化的约定写在这里，比如代码风格、目录规范、禁止依赖第三方库等。

口头提醒只对当前会话有用，一旦重启会话，模型就会忘记。如果不在 CLAUDE.md 中维护约定，重复浪费 Token 是必然的。

6.3 利用 Git 做变更回滚

Claude Code 在快速开发时，可能连续修改多个文件。如果其中某次修改不符合预期，最好的回退方式不是让它在当前代码上反向修改，而是使用 Git 回退到上一个可用版本。

建议在项目一开始就完成 Git 初始化：

git init git add . git commit -m "初始化 Arcade 项目结构"

每完成一个游戏、完成一次 bug 修复后，就提交一次：

git add . git commit -m "完成贪吃蛇游戏基础版本"

这样，如果 Claude Code 在后续迭代中把代码改乱，你可以放心地让它重试，因为你随时可以通过 Git 回到稳定状态。这是避免“AI 越修越乱”最有效的手段。

6.4 先让 Claude Code 自查，再让你自己验证

Claude Code 具备执行命令的能力，因此在网页游戏项目中，你可以要求它在完成代码后做自查：

完成代码后，请检查是否有明显的逻辑错误，并运行 node --check game.js 验证 JavaScript 语法是否正确。如果发现错误，请修复后再回复我。

对于纯前端页面，node --check只能验证语法，不能验证运行逻辑。最终的交互逻辑必须由你在浏览器中操作验证。这一点不要完全交给模型。

更进一步的实践是让 Claude Code 帮你写一个简单的测试脚本。虽然小游戏项目写单元测试比较繁琐，但纯逻辑模块（比如生成网格、判断碰撞、洗牌函数）可以抽出来测试。

6.5 密钥与配置文件安全

Claude Code 运行时需要访问模型服务的 API 密钥或登录凭证。这些凭据必须远离项目目录。

建议在项目目录中创建.gitignore，并把常见敏感文件排除掉：

node_modules/ .env *.local settings.json

如果你使用 API Key 方式，强烈建议通过环境变量注入，而不是写入任何项目代码中。一旦发现 API Key 被提交到了公开仓库，应当立即到云平台吊销并重新生成。

6.6 Token 消耗控制

Claude Code 虽然能力强，但多轮对话会持续消耗 Token。Arcade 这种需要反复修改和调试的项目，如果使用量比较大，建议注意以下控制手段：

• 不要把完整文件反复粘贴进对话，直接告诉 Claude Code “请打开 games/snake/game.js 查看”即可。
• 对已经稳定的文件减少无意义的反复修改。
• 一个会话内围绕同一模块连续操作，减少跨主题跳转。
• 使用--resume或会话恢复机制继续历史任务，避免重新加载大量上下文。
• 每次完成阶段性功能后提醒 Claude Code “总结本次变更和下一步计划”，方便控制任务范围。

6.7 对代码生成结果做人工审查

无论 Claude Code 在当前项目上表现多好，它生成的代码都应当经过人工审查，尤其是在动画循环、事件监听、定时器清理这些容易出问题的场景。

例如贪吃蛇项目中，如果setInterval没有在游戏结束时清理，页面可能会同时存在多个游戏循环，导致蛇的移动速度越来越快。Claude Code 第一次生成的代码未必能处理好所有生命周期问题，这就需要开发者有基本的代码审查意识。

7. 总结与下一步可做的事

通过 Claude Code Arcade 这个项目，你可以把 Claude Code 从“偶尔帮你写函数的小工具”变成“能独立完成小项目的 AI 开发代理”。整个流程中你应该已经掌握几件事：如何安装 Claude Code，如何用 CLAUDE.md 维护项目约定，如何用任务式 Prompt 让模型分步开发，如何通过本地服务器验证前端页面，以及如何处理常见安装和配置报错。

如果你的目标是继续深入，可以考虑以下几个方向：

• 给游戏增加更多变体，比如把贪吃蛇改成“穿墙模式”或“障碍物模式”，观察 Claude Code 在现有代码上做功能扩展的能力。
• 引入测试框架，让 Claude Code 在修改代码后自动执行回归验证。
• 使用真实业务项目做一次“AI 结对编程”，看 Claude Code 在包含后端、数据库、中间件的复杂项目中是否依然能保持稳定产出。
• 认真阅读 Claude Code 每次操作生成的 diff 文件，建立自己的 AI 代码审查习惯。这比单方面要求模型“不要出错”更可靠。

最后留一个小建议：如果你在本地把 Arcade 项目跑通了，不要只停留在完成界面，找一个经典小游戏重新做一遍。你会发现，真正的难点从来不是生成第一次代码，而是让 AI 在已有代码上做局部修改而不破坏其他功能，这才是把 AI 编程工具用于生产项目前必须跨过的一道坎。