之前很长一段时间我的个人网站一直挂在 Framer 上。Framer 做视觉稿确实好看拖拽排版、动画曲线、响应式预览都很顺手但它本质上是一个“设计优先”的在线编辑器。改一次全局字体、调一组间距、换一套响应式断点都要在浏览器里手动点来点去。等网站内容多起来之后页面层级越来越深导出的代码也不够干净继续在上面维护的成本反而变高了。后来我花了几天时间用 Claude Code 作为主力编程助手把个人网站从 Framer 完整迁到了 Astro 静态站点并顺手把视觉和内容结构重新设计了一遍。整个过程让我觉得 Claude Code 并不是一个“帮你补全代码”的玩具而是一个能真正参与项目重构的协作工具。本文就把这次迁移的完整思路、安装配置、核心文件、踩坑记录和工程建议整理出来给同样想从可视化建站迁到代码建站、或者正在用 Claude Code 做真实项目的开发者一个参考。1. 为什么要把个人网站从 Framer 迁到 Claude Code1.1 Framer 的便利与瓶颈Framer 这类可视化建站工具的核心优势是不需要懂代码也能在短时间内做出视觉效果很精致的页面。对于作品集、落地页、营销页来说它确实效率很高。但当你开始把网站当作长期产品来维护时会遇到几个比较现实的瓶颈内容越多Framer 的图层和断点管理越混乱改一个组件可能影响多个页面。自定义交互和代码注入的能力有限超出平台封装范围的需求很难实现。站点托管、域名、SEO 配置都依赖平台迁移成本被锁定。导出的代码往往带有一堆平台私有标记无法直接交给后续维护。换句话说Framer 更适合“快速做出一个漂亮页面”但不太适合“长期维护一个可以扩展的个人网站”。这也是我决定迁移的最主要原因。1.2 Claude Code 是什么Claude Code 是 Anthropic 推出的终端式 AI 编程助手它不是一个聊天窗口而是直接运行在你的项目目录里可以读取代码、修改文件、执行命令、运行测试甚至按照你的要求完成一次多文件重构。你只需要在终端里启动它然后用自然语言描述需求它会基于当前项目的上下文给出修改方案并落地到文件。它的工作方式和传统 AI 补全工具最大的区别在于“代理式协作”它能看到项目里的真实文件结构而不是只盯着当前打开的文件。它可以连续执行多步操作比如“先读取配置文件再修改组件最后运行构建验证”。它支持项目级记忆CLAUDE.md可以在每次会话开始时自动加载项目规则。它可以通过 Skills 扩展专项能力比如设计走查、SEO 检查、代码审查等。对我这次迁移来说Claude Code 最有价值的一点是我只需要把旧的 Framer 站点内容整理成结构化的 Markdown 和设计规范它就能批量生成 Astro 页面、组件和样式这比手工重写快得多。1.3 迁移之后能得到什么把个人网站从 Framer 迁到 Claude Code 静态站点方案后我认为最核心的收益并不是“免费”或者“更极客”而是下面几点维度Framer 方案Claude Code Astro 方案代码可控性平台私有结构完全拥有源码页面扩展依赖平台组件任意的 HTML/CSS/JS 组件SEO 优化平台内置但不灵活可精确控制 meta、sitemap、结构化数据部署方式平台托管Vercel / Netlify / 任意静态托管改版效率手动点选自然语言描述AI 直接改代码当然迁移并不是没有成本。你需要掌握基础的 Git、命令行、HTML/CSS以及至少能看懂静态站点框架的目录结构。这也是为什么我把这篇文章定位成“新手也能跟完的实战教程”而不是只讲概念。2. 环境准备与安装2.1 检查 Node.js 环境Claude Code 官方推荐通过 npm 安装所以第一步是确认本机有 Node.js 环境。打开终端执行node -v npm -v如果两条命令都能输出版本号说明环境正常。如果提示command not found需要先去 Node.js 官网下载 LTS 版本安装。建议使用 Node.js 18 及以上版本版本过低时 Claude Code 可能无法正常运行。如果你平时会切换多个 Node 版本推荐使用 nvm 管理nvm install 20 nvm use 202.2 安装 Claude Code在确认 Node.js 环境正常后用 npm 全局安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后验证版本号claude --version如果能输出版本信息说明安装成功。这里需要注意不同操作系统下全局安装目录不同Windows 上可能是 npm 的全局 bin 目录macOS/Linux 上通常位于/usr/local/bin或 nvm 对应目录。如果安装后终端仍然找不到claude命令优先检查 npm 全局 bin 目录是否在 PATH 环境变量中。2.3 登录与首次对话安装完成后在任意项目目录下运行claude首次启动会引导你登录 Claude 账号或者配置 API Key。登录方式以当前版本实际提示为准一般会有网页授权和 Key 粘贴两种途径。登录成功后你会进入一个交互式终端界面可以直接输入需求。我们先做一个最简单的测试让它输出当前目录结构claude 列出当前目录下的所有文件和文件夹并说明每个文件的用途如果它能正确读取目录并给出解释说明工具已经可以正常使用了。2.4 三种使用形态CLI、VS Code 插件、桌面版Claude Code 常见的使用形态有三种你可以根据自己的习惯选择终端 CLI 形态最核心的用法适合执行批量重构、运行命令、跨文件修改。VS Code 插件形态在编辑器侧边栏打开对话面板适合边看代码边修改搜索 “Claude Code” 插件安装即可。桌面版形态适合不熟悉命令行的用户安装后通过图形界面创建项目、打开文件夹。我这里主要使用终端 CLI 形态因为它和构建、部署、脚本执行的配合最直接。3. Claude Code 的核心工作方式3.1 CLAUDE.md让 AI 记住项目规则Claude Code 启动后会查找项目根目录下的CLAUDE.md文件并把它作为项目级上下文自动加载。这是整个协作流程里最重要的配置文件相当于给 AI 写了一份“项目说明书”。我迁移个人网站时在项目根目录建了这样的CLAUDE.md# 个人网站项目说明 ## 技术栈 - Astro TypeScript - CSS 自定义属性变量做设计系统 - 部署目标Vercel / Netlify ## 目录约定 - src/pages 存放页面路由 - src/components 存放可复用组件 - src/styles 存放全局样式与设计变量 - src/content 存放 Markdown 内容集合 ## 开发规范 - 所有页面必须包含 title 和 description 的 meta 标签 - 颜色只能使用 styles/tokens.css 中定义的变量禁止硬编码色值 - 组件样式使用 scoped style不要影响全局这样配置之后每次开启新会话Claude Code 都会自动遵守这些规则不需要反复提醒。实际体验中这比在对话里临时描述需求稳定得多。3.2 settings.json控制模型与权限Claude Code 也支持通过配置文件控制模型、权限和默认行为。常见的位置是项目目录下的.claude/settings.json或者用户目录下的全局配置。下面是一个常见配置示例{ model: claude-sonnet-4-5, permissions: { allow: [ Bash(npm run dev), Bash(npm run build), Read(**), Write(src/**) ], deny: [ Write(.env), Write(.git/**) ] } }这里的含义是model指定默认使用的模型具体可用的模型名以你的账号权限和当前版本为准。permissions.allow表示允许 Claude Code 自动执行的操作比如允许读取所有文件、允许修改src目录下的文件、允许运行开发构建命令。permissions.deny表示禁止的操作这是安全边界比如禁止修改.env密钥文件。这个配置的价值在于你不需要在每次对话时都确认权限请求同时又能把高危操作隔离在外。3.3 Skills扩展专项能力Skills 是 Claude Code 的另一项重要能力它可以让你把一套固定的“专家流程”封装起来。比如我封装了一个“设计走查”技能每次让 Claude Code 对页面做视觉审查时它会自动按照我定义的检查清单逐项检查而不是每次都要重新描述。一个 Skill 本质上是项目.claude/skills/目录下的一个子目录里面包含一个SKILL.md文件格式大致如下--- name: design-review description: 对个人网站页面进行设计走查输出可执行的改进清单 --- # 设计走查任务 执行本技能时请按以下流程操作 1. 读取目标页面的源码和样式文件。 2. 检查间距是否使用设计变量是否存在硬编码色值。 3. 检查标题层级是否合理重点内容是否在首屏。 4. 检查移动端断点下的布局是否出现横向滚动。 5. 输出改进清单按优先级排序并直接给出修改建议。之后在对话中只要说“对首页执行 design-review”Claude Code 就会按照这个流程执行。对于站点改版这种重复性很强的工作Skills 能把效率提升一个档次。3.4 高频 CLI 命令与交互技巧除了直接claude 需求的用法还有几个高频命令可以收藏# 继续上一次会话 claude --continue # 恢复指定会话 claude --resume # 在非交互模式下执行一次性任务 claude -p 读取 README.md 并总结项目用途 # 跳过权限确认仅限完全信任的项目不建议常开 claude --dangerously-skip-permissions在交互界面内还有一些常用斜杠命令比如/clear清空上下文、/compact压缩长时间对话、/cost查看本次会话的 token 消耗。这些命令可以帮你控制对话长度和成本。4. 迁移实战把 Framer 站点改造成 Astro 静态站接下来是本文的核心部分我如何把旧 Framer 网站迁移到 Astro 静态站点并用 Claude Code 辅助完成重构与再设计。下面按步骤拆解。4.1 盘点旧站结构与内容迁移前最重要的工作不是写代码而是盘点内容。我先从旧站整理出了完整站点地图原 Framer 页面迁移后页面对应文件首页 Hero首页src/pages/index.astroWork 项目列表作品页src/pages/work/index.astro单个项目详情项目详情页src/pages/work/[slug].astroAbout 自我简介关于页src/pages/about.astroContact 联系表单联系页src/pages/contact.astro然后我把每个页面的文案、图片、外链整理成 Markdown 文件。这样做的原因是Claude Code 处理 Markdown 内容的稳定性远高于让它从 Framer 导出的混乱 HTML 里反推信息。迁移内容本质上就是先把内容从“平台私有格式”里释放出来再重新组织进代码项目。4.2 建立设计系统与全局样式旧站在 Framer 里虽然视觉统一但很多颜色和间距是分散的。迁到代码项目后我第一件事是把它们收敛成设计变量新建src/styles/tokens.css:root { --color-bg: #faf9f7; --color-text: #1a1a1a; --color-muted: #6b6b6b; --color-accent: #ff5a36; --color-border: #e8e5e0; --font-sans: Inter, system-ui, -apple-system, sans-serif; --font-serif: Source Serif 4, Georgia, serif; --space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem; --space-8: 2rem; --space-12: 3rem; --space-16: 4rem; --container: 72rem; --radius: 12px; --transition: 0.2s ease; }这些变量会成为后面所有组件的基础。Claude Code 在生成组件时我会明确要求“颜色和间距只能引用 tokens.css 里的变量”这样整个站点的视觉一致性就有了保障。4.3 用 Claude Code 生成页面与组件在项目骨架搭好之后我让 Claude Code 负责生成具体组件。先创建 Astro 项目npm create astrolatest personal-site -- --template minimal cd personal-site npm install然后安装基础依赖npm install fontsource/inter接着就可以开始让 Claude Code 工作了。比如生成首页 Hero 区域claude 在 src/components 下创建 Hero.astro要求使用设计变量标题用 serif 字体副标题用 muted 颜色右侧预留一张项目截图区域整体响应式它会自动生成类似下面的组件文件路径src/components/Hero.astro--- // src/components/Hero.astro interface Props { title: string; description: string; imageSrc: string; } const { title, description, imageSrc } Astro.props; --- section classhero div classhero__content p classhero__eyebrow欢迎来到我的个人网站/p h1 classhero__title{title}/h1 p classhero__description{description}/p a classhero__cta href/work查看作品/a /div div classhero__media img src{imageSrc} alt项目截图 loadinglazy / /div /section style .hero { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-12); max-width: var(--container); margin: 0 auto; padding: var(--space-16) var(--space-4); } .hero__eyebrow { color: var(--color-muted); text-transform: uppercase; letter-spacing: 0.08em; font-size: 0.875rem; } .hero__title { font-family: var(--font-serif); font-size: clamp(2rem, 5vw, 3.5rem); line-height: 1.1; margin: var(--space-4) 0; } .hero__description { color: var(--color-muted); max-width: 36rem; margin-bottom: var(--space-8); } .hero__cta { display: inline-block; background: var(--color-accent); color: #fff; padding: var(--space-2) var(--space-4); border-radius: var(--radius); text-decoration: none; } .hero__media img { width: 100%; border-radius: var(--radius); box-shadow: 0 8px 24px rgb(26 26 26 / 12%); } media (max-width: 768px) { .hero { grid-template-columns: 1fr; gap: var(--space-8); } } /style之后在页面里引用这个组件比如src/pages/index.astro--- // src/pages/index.astro import Layout from ../layouts/Layout.astro; import Hero from ../components/Hero.astro; --- Layout title首页 description我的个人网站首页 Hero title你好我是前端开发者 description这里记录我的项目、文章和日常思考。 imageSrc/images/hero-project.png / /Layout这只是一个示例流程。实际迁移时页面多、组件多我不会逐个手动敲代码而是把站点地图和设计规范一次性交给 Claude Code让它分批生成并在每批生成后跑一次npm run build验证。4.4 接入第三方模型可选Claude Code 默认使用官方模型但如果你所在团队或服务商提供了 Anthropic 兼容接口也可以通过环境变量切换模型服务。这里以兼容接口为例思路如下export ANTHROPIC_BASE_URLhttps://api.example.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODELdeepseek-chat claude需要注意几点前提是服务商真的提供了 Anthropic 兼容接口且接口路径、鉴权方式与 Claude Code 预期一致。模型名称必须写成服务商实际支持的名称写成官方模型名会出现 “xxx is not a model this version of claude code recognizes” 的报错。密钥不要写进项目的 settings.json更不要提交到 Git建议通过环境变量或本机密钥管理器注入。社区里也有一些配置切换工具例如 cswitch 之类的模型配置管理工具核心作用就是帮你快速切换不同服务的 base_url、token 和模型名。如果你只在官方模型和第三方模型之间偶尔切换手动维护环境变量脚本也足够了。4.5 本地运行与构建验证迁移过程中我会随时本地启动开发服务预览npm run dev打开终端提示的本地地址通常是http://localhost:4321逐页检查。确认没有问题时执行生产构建npm run build npm run previewnpm run build会生成dist/静态目录npm run preview会以生产模式预览构建结果。这一步非常关键很多问题在开发模式看不出来但到了构建阶段会暴露比如引用不存在路径、SSG 页面数据缺失、组件样式作用域错误等。构建通过后把项目推送到 Git 仓库再关联 Vercel 或 Netlify 即可自动部署。部署完成后记得把旧域名的 DNS 记录迁移过去并配置新的 301 重定向避免旧地址失效。5. 常见问题与排查思路5.1 安装与启动类问题问题现象常见原因解决思路提示command not found: claudenpm 全局 bin 目录不在 PATH 中重启终端或执行npm bin -g查看目录并加入 PATH提示could not locate the claude cli on path某些插件或脚本找不到 claude 命令确认全局安装成功重启终端在插件设置里指定 claude 可执行文件路径启动后一直转圈无法进入对话网络连接或登录态失效检查网络与账号登录状态退出后重新登录查看官方状态页VS Code 插件无法识别 Claude Code插件版本与 CLI 版本不一致同时升级 CLI 和插件到最新版本这里要特别说明一下如果是在 VS Code 里使用 Claude Code 插件通常要求系统里先安装好 CLI因为插件本质上是在调用已有的claude命令。遇到 “could not locate the claude cli on path” 时优先排查 CLI 是否安装成功而不是插件本身的设置。5.2 模型接入与配置类问题问题现象常见原因解决思路报错xxx is not a model this version of claude code recognizes配置的模型名称与当前服务商/版本不一致改成服务商实际支持的模型名确认模型白名单报错 529服务端限流或配额不足稍后重试降低请求频率切换到低负载模型检查套餐额度新建的 settings.json 不生效配置文件路径或字段名不对确认放在项目.claude/settings.json或用户全局配置目录检查 JSON 格式组织账号提示无法使用订阅访问企业策略限制了 Claude 订阅联系管理员确认策略使用个人账号测试第三方模型能对话但经常中断服务商接口兼容性不完整回退到官方模型或选用兼容性更好的服务商其中 529 错误是最常见的限流问题。它的本质是服务端短期负载过高或账号配额用尽排查顺序一般是先看套餐额度是否用完再看是不是单次任务请求量过大最后再考虑是否切换模型。5.3 内容与部署类问题问题现象常见原因解决思路迁移后图片 404图片路径和文件名不一致统一图片放到public/images用相对正确路径引用页面 meta 描述缺失模板没有注入 title/description在 Layout 组件里统一处理 meta 标签旧站链接失效只迁移了首页没做重定向在部署平台配置重定向规则把旧路径 301 到新路径构建产物空白页页面组件发生运行时错误先执行npm run build查看报错检查组件 props 是否缺省6. 最佳实践与工程建议6.1 把大任务拆成小步提交Claude Code 虽然能一次完成多文件修改但我的建议是不要让它一口气重写整个网站。更稳妥的方式是一个页面或者一个组件作为一个任务单元完成后立即git commit。这样即使某一步生成的结果不满意也能随时回滚不会影响其他已经验证过的部分。6.2 维护好 CLAUDE.md 与项目文档CLAUDE.md 是 Claude Code 的“长期记忆”也是项目交接给 AI 时的契约。建议在项目早期就写好之后每次改动目录结构、引入新依赖、改变样式规范时同步更新它。你会发现CLAUDE.md 维护得越细后续让 Claude Code 生成的代码就越符合预期反复修改的次数越少。6.3 权限、密钥与安全边界使用 AI 编程助手时权限控制一定要重视。我给自己定的规则是.env、私钥、配置密钥文件一律写入permissions.deny禁止 AI 读取和修改。尽量少用--dangerously-skip-permissions只在完全信任的临时环境里使用。涉及删除文件、批量重命名、修改 Git 历史等操作先让 Claude Code 输出执行计划人工确认后再执行。所有密钥只通过环境变量注入不写进配置文件。6.4 部署与上线清单迁移上线前建议按下面的清单检查一遍本地npm run build是否零报错。首页、作品页、关于页、联系页是否都能正常访问。手机宽度下是否出现横向滚动。是否有硬编码色值残留搜索#开头且不是设计变量的颜色值。每个页面是否有独立的 title 和 description。旧站是否配置了 301 重定向。域名 DNS 是否已经切换HTTPS 证书是否生效。7. 总结与下一步学习路线这次从 Framer 迁到 Claude Code Astro 的完整流程让我重新理解了“用 AI 做网站”这件事。真正高效的方式不是让 AI 一次性生成整个站点而是把它当作一个随时可调用的前端协作成员你负责整体架构、内容边界、设计规范和安全策略它负责把需求和规范翻译成可运行的代码然后你在构建结果上做走查和修正。如果你想继续深入建议按这个顺序往下学先把 Claude Code 安装配置好在一个简单项目里跑通 CLAUDE.md 和 settings.json。再试着把一个小页面交给它重构熟悉它的生成风格和权限交互。然后封装一个自己的 Skill比如“组件代码审查”或“SEO 走查”。最后再把完整的 Framer 旧站做迁移过程中不断更新你的 CLAUDE.md。个人网站这种体量适中、边界清晰、又可以反复改版的项目非常适合作为学习 Claude Code 和静态站点的练习场。如果你在迁移时也遇到了有趣的报错或者好用的配置技巧欢迎在评论区交流。
