本文适用范围

本文按 2026-08-26 的官方文档与当前 Windows 原生安装方式编写。Claude Code 更新频率很高，安装器、默认权限模式与界面文案后续可能变化；如果你在未来阅读，版本敏感步骤应优先以官方文档为准。

常见说法

截至 2026-08-26 的情况

本文采用的做法

“安装 Claude Code 必须先装 Node.js 18+”

对原生 Native Install 已不成立；npm 仍是高级安装选项之一

Claude Code 本体用原生安装；Node.js 只为后面的示例项目安装

“Windows 只能通过 WSL 使用”

已过时；官方支持原生 Windows，也支持 WSL 1/2

新手主线使用原生 Windows；Linux 工具链再考虑 WSL 2

“Git for Windows 是硬性依赖”

当前为可选；有 Git Bash 时可使用 Bash，没有则用 PowerShell

建议开发者安装，但不把它当安装前置条件

“必须管理员身份运行 PowerShell”

官方明确原生安装不需要管理员权限

普通 PowerShell 即可，避免无意义地提升权限

“免费 Claude.ai 账号装完就能用”

官方说明 Claude Code 需要 Pro/Max/Team/Enterprise、Console 或受支持云提供商

安装前先确认账号与访问条件，避免装完卡在登录

为什么先做这张纠偏表

安装类文章最怕“步骤看起来完整，但前提已经过时”。先确定当前支持边界，后面的每一步才有可复现意义。

项目

当前要求或建议

说明

操作系统

Windows 10 1809+ / Windows Server 2019+

Windows 11 同样支持

处理器

x64 或 ARM64

以当前官方支持架构为准

内存

4 GB+

实际大型项目建议预留更多内存给 IDE、浏览器和构建工具

网络

需要互联网连接

认证和模型调用需要网络；企业网络还可能涉及代理/证书

Shell

PowerShell、CMD；也可使用 Git Bash / WSL

本文使用 PowerShell

账号

Claude Pro/Max/Team/Enterprise、Claude Console 或受支持云提供商

免费 Claude.ai 计划当前不包含 Claude Code

两个最常见的“命令复制错终端”错误

如果看到 “irm 不是内部或外部命令”，通常说明你在 CMD；如果看到 “&& 不是有效的语句分隔符”，通常是把 CMD 命令粘进了 PowerShell。

irm https://claude.ai/install.ps1 | iex

claude --version
claude doctor

推荐习惯

遇到“明明装了却不工作”的问题，不要第一反应就卸载重装。先跑 claude doctor，通常能更快定位 PATH、配置或安装状态问题。

winget install Anthropic.ClaudeCode

# 后续手动升级
winget upgrade Anthropic.ClaudeCode

claude

登录失败不要和安装失败混为一谈

“claude --version 能正常输出，但 claude 无法完成登录”说明 CLI 本体大概率已经安装成功。下一步应检查账号类型、地区支持、网络/企业代理以及认证状态，而不是反复重装。

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

node -v
npm -v

mkdir windows-claude-todo
cd windows-claude-todo

# 如果你已经安装 Git，建议顺手初始化
git init

claude

claude --permission-mode plan

你现在位于一个空的 Windows 项目目录。请先用 5 条以内的计划说明你准备怎么做，得到我确认后再开始修改文件。

目标：创建一个“全栈任务看板”Web 应用，并在本机跑通。

技术约束：
1. 运行环境使用 Node.js 24 LTS。
2. 尽量零依赖：后端优先使用 node:http、node:fs、node:path 等内置模块。
3. 前端使用原生 HTML + CSS + JavaScript，不使用 CDN，不依赖外网资源。
4. 数据持久化到 data/tasks.json。
5. 使用 ES Module。

功能要求：
- GET /api/tasks：读取任务列表。
- POST /api/tasks：新增任务，title 必须为 1～80 个字符。
- PATCH /api/tasks/:id：修改标题或完成状态。
- DELETE /api/tasks/:id：删除任务。
- 首页可以新增、勾选完成、删除任务，并展示总数与已完成数量。
- 页面要适配手机宽度，所有用户可见文案使用简体中文。

工程要求：
- package.json 提供 npm start 和 npm test。
- 使用 node:test 写至少两个测试：一个覆盖 CRUD 闭环，一个覆盖空标题返回 400。
- 写 README.md，说明环境、启动、测试和目录结构。
- 对 JSON 解析、404、405、输入校验给出明确错误响应。
- 不要读取或输出任何系统密钥、浏览器凭据或无关目录内容。

完成标准：
1. 先生成项目文件。
2. 运行 npm test；如果失败，定位原因并修复，直到测试通过。
3. 短暂启动服务，验证 http://localhost:3000 和 GET /api/tasks 可访问，然后停止用于验证的后台进程。
4. 最后告诉我：修改了哪些文件、测试结果、启动命令、浏览器访问地址，以及还存在哪些边界。

windows-claude-todo/
├─ public/
│  ├─ index.html
│  ├─ app.js
│  └─ styles.css
├─ data/
│  └─ tasks.json
├─ test/
│  └─ api.test.mjs
├─ server.mjs
├─ package.json
└─ README.md

方法

路径

目标

正确结果

GET

/api/tasks

读取任务列表

200 + JSON 数组

POST

/api/tasks

新增任务

201 + 新任务对象

PATCH

/api/tasks/:id

更新标题或完成状态

200 + 更新后的任务

DELETE

/api/tasks/:id

删除任务

204 No Content

POST

/api/tasks（空标题）

输入校验

400 + JSON 错误信息

{
  "name": "windows-claude-todo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.mjs",
    "test": "node --test"
  },
  "engines": {
    "node": ">=22"
  }
}

import http from 'node:http';
import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import crypto from 'node:crypto';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const PUBLIC_DIR = path.join(__dirname, 'public');
const DATA_DIR = path.join(__dirname, 'data');
const DATA_FILE = path.join(DATA_DIR, 'tasks.json');
const PORT = Number(process.env.PORT || 3000);

const MIME = {
  '.html': 'text/html; charset=utf-8',
  '.js': 'text/javascript; charset=utf-8',
  '.css': 'text/css; charset=utf-8',
  '.json': 'application/json; charset=utf-8',
};

async function ensureDataFile() {
  await mkdir(DATA_DIR, { recursive: true });
  try { await stat(DATA_FILE); }
  catch { await writeFile(DATA_FILE, '[]\n', 'utf8'); }
}

async function readTasks() {
  await ensureDataFile();
  return JSON.parse(await readFile(DATA_FILE, 'utf8'));
}
async function writeTasks(tasks) {
  await writeFile(DATA_FILE, JSON.stringify(tasks, null, 2) + '\n', 'utf8');
}
function sendJson(res, status, data) {
  res.writeHead(status, { 'content-type': MIME['.json'], 'cache-control': 'no-store' });
  res.end(JSON.stringify(data));
}
async function readJson(req) {
  let body = '';
  for await (const chunk of req) {
    body += chunk;
    if (body.length > 1_000_000) throw new Error('请求体过大');
  }
  return body ? JSON.parse(body) : {};
}
function cleanTitle(value) {
  if (typeof value !== 'string') return '';
  return value.trim().replace(/\s+/g, ' ');
}
function taskPath(url) {
  const match = url.pathname.match(/^\/api\/tasks\/([^/]+)$/);
  return match ? decodeURIComponent(match[1]) : null;
}

export function createServer() {
  return http.createServer(async (req, res) => {
    try {
      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
      if (url.pathname === '/api/tasks' && req.method === 'GET') {
        return sendJson(res, 200, await readTasks());
      }
      if (url.pathname === '/api/tasks' && req.method === 'POST') {
        const body = await readJson(req);
        const title = cleanTitle(body.title);
        if (!title || title.length > 80) return sendJson(res, 400, { error: '任务标题长度必须为 1 到 80 个字符' });
        const tasks = await readTasks();
        const task = { id: crypto.randomUUID(), title, completed: false, createdAt: new Date().toISOString() };
        tasks.unshift(task); await writeTasks(tasks);
        return sendJson(res, 201, task);
      }
      const id = taskPath(url);
      if (id && req.method === 'PATCH') {
        const body = await readJson(req); const tasks = await readTasks();
        const task = tasks.find(t => t.id === id);
        if (!task) return sendJson(res, 404, { error: '任务不存在' });
        if ('title' in body) {
          const title = cleanTitle(body.title);
          if (!title || title.length > 80) return sendJson(res, 400, { error: '任务标题长度必须为 1 到 80 个字符' });
          task.title = title;
        }
        if ('completed' in body) task.completed = Boolean(body.completed);
        await writeTasks(tasks); return sendJson(res, 200, task);
      }
      if (id && req.method === 'DELETE') {
        const tasks = await readTasks(); const next = tasks.filter(t => t.id !== id);
        if (next.length === tasks.length) return sendJson(res, 404, { error: '任务不存在' });
        await writeTasks(next); res.writeHead(204); return res.end();
      }
      if (req.method !== 'GET') return sendJson(res, 405, { error: '不支持的请求方法' });
      let rel = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
      rel = path.normalize(rel).replace(/^(\.\.(\/|\\|$))+/, '');
      const filePath = path.join(PUBLIC_DIR, rel);
      if (!filePath.startsWith(PUBLIC_DIR)) return sendJson(res, 403, { error: '禁止访问' });
      try {
        const data = await readFile(filePath);
        const ext = path.extname(filePath).toLowerCase();
        res.writeHead(200, { 'content-type': MIME[ext] || 'application/octet-stream' });
        res.end(data);
      } catch {
        sendJson(res, 404, { error: '资源不存在' });
      }
    } catch (error) {
      sendJson(res, 500, { error: error?.message || '服务器内部错误' });
    }
  });
}

if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  const server = createServer();
  server.listen(PORT, () => console.log(`任务看板已启动：http://localhost:${PORT}`));
}

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Claude Code 全栈任务看板</title>
  <link rel="stylesheet" href="/styles.css" />
</head>
<body>
  <main class="shell">
    <section class="hero">
      <p class="eyebrow">WINDOWS × CLAUDE CODE</p>
      <h1>全栈任务看板</h1>
      <p>前端、REST API 与本地数据持久化一次跑通。</p>
    </section>
    <section class="panel">
      <form id="task-form">
        <input id="task-input" maxlength="80" placeholder="输入一个待办事项，例如：验证 Claude Code 安装" autocomplete="off" />
        <button>添加任务</button>
      </form>
      <div class="stats"><span id="total">0 项任务</span><span id="done">0 项完成</span></div>
      <ul id="task-list"></ul>
      <p id="empty" class="empty">还没有任务，先添加第一项吧。</p>
    </section>
  </main>
  <script type="module" src="/app.js"></script>
</body>
</html>

const list = document.querySelector('#task-list');
const empty = document.querySelector('#empty');
const total = document.querySelector('#total');
const done = document.querySelector('#done');
const form = document.querySelector('#task-form');
const input = document.querySelector('#task-input');
let tasks = [];

async function api(url, options = {}) {
  const res = await fetch(url, { headers: { 'content-type': 'application/json' }, ...options });
  if (!res.ok) { const body = await res.json().catch(() => ({})); throw new Error(body.error || `请求失败：${res.status}`); }
  return res.status === 204 ? null : res.json();
}
function render() {
  list.innerHTML = '';
  for (const task of tasks) {
    const li = document.createElement('li');
    li.className = task.completed ? 'done' : '';
    li.innerHTML = `<input class="toggle" type="checkbox" ${task.completed ? 'checked' : ''}><span class="title"></span><button class="icon-btn" aria-label="删除">删除</button>`;
    li.querySelector('.title').textContent = task.title;
    li.querySelector('.toggle').addEventListener('change', async e => {
      const updated = await api(`/api/tasks/${task.id}`, { method:'PATCH', body:JSON.stringify({completed:e.target.checked}) });
      tasks = tasks.map(t => t.id === updated.id ? updated : t); render();
    });
    li.querySelector('button').addEventListener('click', async () => {
      await api(`/api/tasks/${task.id}`, { method:'DELETE' }); tasks = tasks.filter(t => t.id !== task.id); render();
    });
    list.append(li);
  }
  total.textContent = `${tasks.length} 项任务`;
  done.textContent = `${tasks.filter(t => t.completed).length} 项完成`;
  empty.hidden = tasks.length > 0;
}
form.addEventListener('submit', async e => {
  e.preventDefault(); const title = input.value.trim(); if (!title) return;
  const task = await api('/api/tasks', { method:'POST', body:JSON.stringify({title}) });
  tasks.unshift(task); input.value=''; render();
});
try { tasks = await api('/api/tasks'); render(); }
catch (e) { empty.hidden = false; empty.textContent = `加载失败：${e.message}`; }

import test from 'node:test';
import assert from 'node:assert/strict';
import { rm, writeFile, mkdir } from 'node:fs/promises';
import { createServer } from '../server.mjs';

const dataFile = new URL('../data/tasks.json', import.meta.url);
async function withServer(fn) {
  await mkdir(new URL('../data/', import.meta.url), { recursive: true });
  await writeFile(dataFile, '[]\n', 'utf8');
  const server = createServer();
  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
  const { port } = server.address();
  try { await fn(`http://127.0.0.1:${port}`); }
  finally { await new Promise(resolve => server.close(resolve)); }
}

test('任务 API 完成新增、查询、更新、删除闭环', async () => {
  await withServer(async base => {
    let r = await fetch(`${base}/api/tasks`, {method:'POST', headers:{'content-type':'application/json'}, body:JSON.stringify({title:'跑通第一个全栈任务'})});
    assert.equal(r.status, 201); const created = await r.json(); assert.equal(created.completed, false);
    r = await fetch(`${base}/api/tasks`); const list = await r.json(); assert.equal(list.length, 1);
    r = await fetch(`${base}/api/tasks/${created.id}`, {method:'PATCH', headers:{'content-type':'application/json'}, body:JSON.stringify({completed:true})});
    const updated = await r.json(); assert.equal(updated.completed, true);
    r = await fetch(`${base}/api/tasks/${created.id}`, {method:'DELETE'}); assert.equal(r.status, 204);
    r = await fetch(`${base}/api/tasks`); assert.equal((await r.json()).length, 0);
  });
});

test('空标题返回 400', async () => {
  await withServer(async base => {
    const r = await fetch(`${base}/api/tasks`, {method:'POST', headers:{'content-type':'application/json'}, body:JSON.stringify({title:'   '})});
    assert.equal(r.status, 400);
  });
});

npm test

TAP version 13
# Subtest: 任务 API 完成新增、查询、更新、删除闭环
ok 1 - 任务 API 完成新增、查询、更新、删除闭环
# Subtest: 空标题返回 400
ok 2 - 空标题返回 400

# tests 2
# pass 2
# fail 0

为什么这一步对 AI 编程尤其重要

“Claude 说已经完成”不是验收证据；测试进程返回 0、API 状态码符合预期、页面能够实际交互，才是可验证结果。让代理自己运行测试并根据失败输出继续修复，才真正用到了 Agent 工作流。

npm start

任务看板已启动：http://localhost:3000

Invoke-RestMethod -Uri 'http://localhost:3000/api/tasks' -Method Get

$body = @{ title = "用 PowerShell 验证 POST 接口" } | ConvertTo-Json
Invoke-RestMethod `
  -Uri 'http://localhost:3000/api/tasks' `
  -Method Post `
  -ContentType 'application/json' `
  -Body $body

层次

本项目做了什么

你验证到了什么

前端

HTML/CSS/JS 页面与交互

浏览器能新增、完成、删除任务

接口

REST API + 状态码 + JSON 错误

前端通过 HTTP 与后端解耦

后端

Node.js HTTP 服务与输入校验

服务端负责业务边界，而不是只靠前端限制

数据

tasks.json 本地持久化

刷新页面后数据仍然存在

测试

node:test 自动化 API 测试

CRUD 与错误场景能重复验证

运行

npm start + localhost

最终成果是真正可访问的程序，而不是代码片段

# 项目说明

## 运行环境
- Windows 10/11
- Node.js 24 LTS
- 启动：npm start
- 测试：npm test

## 架构约束
- 前端文件位于 public/
- REST API 位于 server.mjs
- 数据写入 data/tasks.json
- 不引入第三方依赖，除非任务明确要求

## 修改规则
- 修改 API 后必须运行 npm test
- 新增用户可见文案必须使用简体中文
- 删除文件或改变数据格式前先说明影响
- 不读取或输出密钥、浏览器凭据和无关用户目录

命令

用途

适合什么时候用

claude

启动交互会话

进入项目开始工作

claude --version

查看版本号

安装后确认

claude doctor

检查安装与配置健康度

PATH/配置/更新问题

claude -c

继续当前目录最近一次会话

中断后继续

claude -r

选择并恢复历史会话

需要回到更早的任务

claude -p "问题"

一次性执行并输出结果

脚本或快速查询

/help

查看会话命令

忘记命令时

/login

重新登录或切换账号

认证发生变化

/init

生成/改进项目 CLAUDE.md

第一次把项目规则固化

/context

查看上下文占用与加载内容

排查 Claude 为什么没看到某些规则

/clear

清空当前会话历史

任务切换、上下文污染时

Shift+Tab

切换权限模式

计划、手动确认和自动模式之间切换

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

最重要的转变

把 Claude Code 当成“会写代码的同事”，而不是“一次性代码生成器”：先说明验收标准，让它动手，再用工具输出验证。这样才真正发挥终端 Agent 的价值。