最近在 Ubuntu 上折腾了一个有意思的小项目用 Claude Code 直接生成一个记账网页。整个过程比我想象中快很多从装好环境到跑出一个能增删改查、带统计的记账页面也就二十分钟左右。这篇就记录一下我是怎么做的、踩了哪些坑以及 Claude Code 在 Linux 上实际用起来的真实体验。我先说结论如果你手头有一台 Ubuntu 机器想快速验证 AI 编程工具的效率拿“记账网页”这种需求明确、边界清晰的小项目开刀是最合适的。它不涉及复杂的后端架构又能覆盖文件生成、逻辑补全、样式调整、脚本执行这些 Claude Code 的典型能力。无论你是刚接触 Linux 的新手还是想评估 AI 辅助开发靠不靠谱的开发者这篇内容都能给你一个可直接照做的路径。1. 项目解读与整体思路1.1 这个项目到底在做什么记账网页听起来很普通但作为 Claude Code 的实践项目却非常典型。它的核心需求很简单用户能输入一笔收入或支出选择分类填金额和备注然后页面能把所有记录按时间排列出来再算一个结余可能还要有月度统计或者分类占比。这类需求不会让人陷入“到底怎么设计架构”的纠结但功能点又足够多正好可以用来测试 AI 编程工具理解自然语言、拆解任务、生成可用代码的综合能力。我选择在 Ubuntu 上做这个不是因为 Windows 或 macOS 不行而是因为 Ubuntu 本身对开发者更友好终端操作直接权限模型清晰几乎所有 AI 编程工具的原生环境都优先支持 Linux。Claude Code 作为一个命令行形态的编程助手在 Ubuntu 的终端里跑起来是最顺的。整个项目实际上就是一个静态网页数据保存在浏览器本地不需要数据库不需要服务器所以它的完成度可以非常高但又不会因为环境复杂而让问题排查变得困难。1.2 为什么选择 Claude Code 而不是直接手写第一反应可能是“记账网页这么简单我自己写也就半小时何必用 AI”这句话对也不是不对。如果你已经写过很多类似的页面脑子里早就有了模板那确实不需要 AI。但如果你是第一次写或者你平时不写前端Claude Code 的价值就出来了它能把“用大白话描述需求”直接变成“可运行的代码”你不需要记住某个元素在 HTML 里怎么写、某个数组方法怎么调、CSS 居中到底是 flex 还是 grid你只需要说清楚你要什么。Claude Code 的原理和搜索引擎或代码补全工具不一样。它不是一个“根据关键词找代码片段”的工具而是会读取你当前项目的文件结构理解上下文然后像一个坐在你旁边的工程师一样帮你创建文件、修改代码、执行命令。你可以让它自己规划任务也可以一步步给它下达指令。对于记账网页这种从零开始的项目最舒服的用法是给它一个清晰的提示词让它先设计一个文件结构然后生成核心代码你在旁边看它执行随时纠正方向。从方案选型上看我刻意避开了 React 或 Vue 这类框架。原因很简单这个项目要验证的是 Claude Code 的生成能力而不是构建工具的配置能力。用纯 HTML 加 CSS 加 JavaScript 的单文件方案文件少、依赖少、跑起来快任何问题都一眼能看出来。后面如果想扩展再让 Claude Code 帮我把逻辑拆成多文件或者接入框架也不迟。2. 环境准备Ubuntu 上的 Claude Code 安装2.1 先搞定基础环境Claude Code 本质上是 Node.js 生态里的一个命令行工具所以第一步不是急着装它而是确认你的 Ubuntu 里有可用的 Node.js 和 npm。我使用的是 Ubuntu 24.04 LTS系统自带的软件源里就有 nodejs 和 npm直接用 apt 安装最省事sudo apt update sudo apt install -y nodejs npm装完以后一定要验证版本这一步很多人会跳过结果后面出了问题又回头猜是不是 Node 版本太低node -v npm -v我当时系统默认装的是 Node.js 18 和 npm 9跑 Claude Code 完全够用。如果你的 Ubuntu 版本比较老apt 里的 Node 可能停留在 12 或 14那建议先升级 Node 到 18 以上。别小看这个版本问题Claude Code 的依赖里有不少新语法Node 太老会直接报错而且报错信息并不直观容易让人误判成安装失败。这里有一个很多教程不会提的小细节npm 全局安装的包需要写到系统目录默认会碰到权限问题。你在执行全局安装命令的时候如果看到EACCES错误别急着在前面加 sudo更干净的做法是配置 npm 的全局目录到用户目录下。两条命令搞定npm config set prefix $HOME/.npm-global export PATH$HOME/.npm-global/bin:$PATH把第二行写到~/.bashrc里以后新开的终端就都能直接跑全局命令了。这个思路适用于所有 npm 全局工具不只是 Claude Code。2.2 安装并配置 Claude Code环境确认没问题之后安装就是一条命令的事npm install -g anthropic-ai/claude-code装完以后运行claude如果是第一次使用它会提示你进行认证。Claude Code 支持多种认证方式最简单的是登录 Anthropic 账号后生成一个 API Key然后在环境变量里指定。我习惯写进~/.bashrcexport ANTHROPIC_API_KEY你的密钥这里要说一下环境变量的加载时机坑过不少人。你改完.bashrc之后如果直接在当前终端跑claude它读取到的还是旧环境变量因为.bashrc只有在新开终端或执行source ~/.bashrc之后才会重新加载。所以改完配置记得先source ~/.bashrc再启动工具否则可能遇到“认证失败”或者“找不到 key”这种让人摸不着头脑的报错。版本更新也是一件容易被忽略的事。Claude Code 更新频率挺高的如果你发现某个功能突然不可用先别怀疑自己操作有误试试升级npm update -g anthropic-ai/claude-code作为命令行工具Claude Code 的交互方式很直接在一个项目目录里敲claude它就进入对话模式你可以一边看它操作文件一边和它讨论。它还能执行 shell 命令比如帮你初始化 git 仓库、启动本地服务器、跑测试脚本这些能力在后面生成记账网页的过程中都会用到。2.3 和 VSCode 协同工作如果你习惯在编辑器里干所有事Claude Code 也可以和 VSCode 配合使用。VSCode 里装好对应的扩展就可以在编辑器侧边栏打开一个 AI 对话面板。我在实际使用中觉得终端形态的 Claude Code 更适合像“生成一个完整网页”这种批量任务因为它会一口气处理多个文件输出全部在终端滚动看着很直观而 VSCode 扩展形态更适合“帮我看明白这一段代码在干嘛”这种局部问题选中代码然后让 AI 解释或重构很顺手。两种形态装好以后我建议你做一个非常基础的测试让它生成一个 hello world 页面确认整条链路是通的再去想记账网页的事。这一步不浪费时间反而能帮你提前暴露认证、网络、路径这一类环境问题避免后面做正式项目时被迫中断。3. 记账网页生成实操全流程3.1 把需求讲清楚提示词怎么写很多人用 AI 编程工具觉得生成结果不满意核心原因往往是需求描述太模糊。你上来就说“帮我做一个记账网页”它只能猜你要什么生成一个通用模板给你。但如果你告诉它“做一个单文件记账页面用 HTMLCSSJS 实现支持添加收入和支出分类可选餐饮、交通、购物、工资等每条记录包括金额、日期、备注用 localStorage 保存页面展示总余额和分类统计”它生成出来的东西就会非常贴近你的真实需求。我给 Claude Code 的提示词大概是这样的请在当前目录生成一个记账网页命名 index.html。要求 1. 使用纯 HTML/CSS/JavaScript放在一个文件里不要引入框架。 2. 支持添加收入和支出记录字段包含金额、分类、日期、备注。 3. 分类内置餐饮、交通、购物、娱乐、工资、其他。 4. 数据用 localStorage 持久化刷新页面不丢失。 5. 页面顶部显示总收入、总支出、结余。 6. 下方展示所有记录列表支持删除单条记录。 7. 样式要简洁现代移动端也能正常看。这里的关键不是“写得长”而是“每一句话都对应一个可验证的功能点”。Claude Code 在生成了代码之后你可以打开页面逐项检查缺什么再单独补。我第一次生成的结果整体可用但发现“分类统计”被我写进要求但它没有完全实现只显示了总额。于是我又追加了一句提示让它把分类统计补上它很快就修改了对应代码。3.2 首屏生成与目录结构解读在一个干净目录里启动 Claude Code 后它会先读取目录内容。空目录的好处是没有任何干扰它可以直接按你的要求创建文件。我当时看到它自己建好了index.html然后在里面逐段写代码整个节奏非常像人类工程师在干活。生成完成后我用浏览器直接打开这个文件发现有一个小问题记录列表里的日期显示格式是英文的我想改成2025-06-14这种格式。于是我又让 Claude Code 修改了日期格式化逻辑。这种迭代方式特别适合 AI 共同工作的场景因为你不需要懂正则表达式或者 Date 对象的具体用法你只需要说你想要什么效果它负责把代码改对。如果你不想用文件协议直接打开 HTML也可以在项目目录起一个简单的本地服务python3 -m http.server 8080然后在浏览器访问http://localhost:8080。我个人建议用这种方式因为它更接近真实网页的运行环境避免某些浏览器在file://协议下对 localStorage 限制不一致的问题。实际上大多数现代浏览器允许 file 协议下用 localStorage但偶尔有隐私模式或安全策略会影响存储用本地服务器就没这些幺蛾子。3.3 功能迭代收入、支出、分类与统计第一版跑通之后记账网页作为“工具”还比较初级真正有价值的是后面几轮迭代。我先让它加了一个“按月份筛选”的功能这样我能看到每个月花了多少、收入多少。实现方式是在顶部加一个下拉框选项来自所有记录里出现的月份选择后列表只显示对应月份的数据。这个功能如果手写需要一个数组去重外加状态管理对写惯业务代码的人来说不难但 Claude Code 只用了几秒钟就写完了。然后是可视化。我让它引入 Chart.js在页面上生成一个饼图展示分类支出占比。这里有个小教训它需要把第三方库的 CDN 链接写进 HTML如果网络环境不稳定页面会一直白屏。我后来为了避免这个问题让它把图表库内嵌成本地文件或者直接删掉饼图改用 CSS 条形图。最终我选择保留一个简单的水平条形图用纯 CSS 实现不需要任何外部依赖加载速度和稳定性都好很多。数据导出也是一个非常实用的迭代项。我提需求加一个“导出 CSV”按钮把当前筛选后的记录下载为 CSV 文件。它很快就实现了而且用了模拟点击下载链接的方式没有引入任何插件。这一项对我这种有记账习惯但不想用第三方 App 的人来说价值比花哨的图表高得多。整个项目从生成到五次迭代一共也就半小时左右。每次改动Claude Code 都只修改相关代码段没有动到其他功能这说明它在处理小型项目时的上下文管理是做得很好的。它的对话轮次越多对项目的理解就越深后续修改的准确率也越高。4. 常见问题与排查技巧4.1 安装环节的坑我整理了一张常见问题速查表这些都是我在实际操作中亲测遇到过的问题现象可能原因解决方案npm 安装报 EACCES 权限错误npm 全局目录不可写配置 npm prefix 到用户目录不要用 sudoclaude命令找不到PATH 未包含 npm 全局 bin 目录在 ~/.bashrc 里 export PATH然后 source 生效认证失败 / API Key 无效环境变量未加载或 Key 过期先 source ~/.bashrc再用echo $ANTHROPIC_API_KEY确认生成过程极慢网络不稳定或并发请求过高检查网络环境稍后重试不要频繁打断生成过程页面打开空白JS 报错或外部 CDN 加载失败打开浏览器开发者工具看 Console 报错移除外部依赖安装阶段最常见的误操作是“用 sudo 强装全局包”。这个做法短期能解决报错但后患无穷因为后续升级、卸载都需要 sudo而且权限混乱可能导致其它工具也受影响。我建议从一开始就用用户级目录干净安全。还有一个很隐蔽的问题出现在 Node.js 版本更新之后。如果你通过 nvm 管理 Node 版本之前全局安装的包在新的 Node 版本下可能丢失运行claude会提示“找不到命令”。这时候重新执行一遍全局安装即可不用慌。4.2 生成过程中的问题Claude Code 在生成代码时偶尔会“跑偏”这是所有 AI 编程工具的共性不能指望它一步到位。我遇到的一个典型情况是我要求所有代码放在一个index.html里它却自作主张拆出了一个style.css和script.js。从工程角度说这个拆分本身是合理的但它违背了我一开始的约束。遇到这种情况不用重新来过直接纠正它“把样式和脚本重新合并回 index.html保持单文件结构”它会照做。另一种常见情况是它生成了一段包含 bug 的 JavaScript比如删除记录时只删了数组里的元素但没有同步更新 localStorage导致页面刷新后记录“复活”了。这种逻辑 bug 光靠阅读代码不容易发现最好的办法就是实际操作一遍。刷新页面、添加记录、删除记录、切换筛选、导出 CSV把每个功能都点一遍只要发现行为不符合预期就把现象描述给 Claude Code让它修。这里要特别提醒AI 工具会非常自然地生成“看起来正确”的代码但它不会主动告诉你某个地方有隐患。比如 localStorage 的 key 名如果没有约定好将来改动字段结构会导致旧数据无法解析。所以你在和它对话时最好让它把存储结构设计的健壮一点比如用版本号标识存储数据的格式。这个问题在简单项目里不致命但能体现你对数据问题的敏感度。4.3 结果不符合预期怎么办当 Claude Code 生成的东西和你想要的不一致第一反应不应该是“这工具不行”而是要问自己我的指令是不是有歧义我见过很多人写“做一个好看一点的界面”然后抱怨 AI 做得不够好看。但“好看”这个标准太主观了它只能按通用审美去套。更务实的做法是给它一个参考方向比如“参考 Tailwind 风格使用白底、浅灰卡片、圆角、细边框主色调用蓝色”它产出的效果会显著提升。另一个实用的技巧是让 Claude Code 自己解释它做了什么。如果某段代码你看不懂直接问它“这段逻辑是什么为什么这样写”它能给你清晰的解释甚至帮你梳理业务逻辑。这比自己去读每一行代码高效得多尤其是你对 JavaScript 不熟的情况下。允许 AI 生成代码不代表你可以做甩手掌柜。至少你要能看懂基本的代码结构知道哪些文件对应哪些功能遇到问题时能快速定位。这也是我做这个记账项目的收获之一它逼着我在没有现成答案的情况下去理解一个完整网页的组成部分。5. 一点个人体会这个记账网页做到最后已经不只是一个工具了更像是我体验“人机协同编程”的一个样本。Claude Code 最让我满意的地方不是它写代码多快而是它“接得住”零散的修改要求。我不用额外教它技术栈不用告诉它 Vue 的生命周期或 CSS 优先级只要描述行为它就能对应到具体代码。如果你也想在 Ubuntu 上试试类似的事情我的建议是别一开始就搞大项目。找一个像记账网页这样边界清晰、功能适中的小需求让 Claude Code 从零到一生成再把你日常使用中遇到的问题当作迭代指令喂给它。等你和它磨合顺了再去尝试更复杂的项目体验会完全不一样。我自己后续可能会在这个记账网页上继续扩展加一个导入导出的 JSON 备份、把统计维度从月度扩展到年度、甚至接一个简单的后端接口做多端同步。每次有新需求大概率都会用和这次相同的方式——在终端里把需求说清楚然后看它动手实现。