用 Claude Code 和 Astro 搭建作品集网站：从需求到上线检查

先明确作品集要替你完成什么任务

作品集网站不是把项目截图堆在一起。它要帮助招聘者、潜在客户、合作伙伴在几分钟内判断：你能解决什么问题、做过什么、联系方式在哪里、是否值得继续沟通。第一版不需要复杂动画，最重要的是信息清楚、加载快、移动端可读。

这里把 Claude Code 当成能读本地代码、编辑文件、运行命令的开发伙伴。可以先查看 Claude Code 官方概览。实现选择 Astro，因为个人作品集大多适合生成静态 HTML，部署简单，也便于做 SEO。Astro 的文件结构可参考官方 Project structure。

如果你还不熟悉 Claude Code，建议先读站内的 Claude Code 入门指南。如果想进一步理解 Astro 项目组织，可以结合用 Claude Code 开发 Astro 一起看。

最小可发布结构

本教程做一个单页作品集：Hero、About、Projects、Services、Contact。不要一开始就加入 CMS、登录、复杂表单或动画库。先让网站能清楚展示你是谁、做过什么、怎样联系，再逐步扩展。

flowchart TD
  A["作品集需求"] --> B["src/data/profile.ts"]
  B --> C["src/pages/index.astro"]
  C --> D["src/styles/global.css"]
  D --> E["npm run build"]
  E --> F["上线前检查"]

建议把个人信息和项目列表放在 src/data/profile.ts，页面只负责渲染。这样之后让 Claude Code 修改文案、调整卡片、替换项目时，差异更小，审查也更容易。

my-portfolio/
  src/
    data/
      profile.ts
    pages/
      index.astro
    styles/
      global.css
  public/
    ogp.png
    projects/
      booking-site.webp

图片放在 public/ 后可以用 /projects/booking-site.webp 访问。MDN 的 img 元素文档建议给图片写清楚 alt，并设置尺寸。位于页面下方的项目截图可以用 loading="lazy"，MDN 的 Lazy loading 也解释了这个属性的用途。

让 Claude Code 先给计划

不要只说“帮我做一个漂亮的作品集”。更稳定的做法是说明读者、文件、限制和完成标准。下面这段可以直接复制给 Claude Code。

我要用 Astro 做一个个人作品集网站。
目标读者是招聘者和小型客户，他们需要在 3 分钟内理解我的能力和项目经验。

要求:
- 单页结构，包含 Hero, About, Projects, Services, Contact
- 数据集中在 src/data/profile.ts
- 实现 src/pages/index.astro 和 src/styles/global.css
- 不引入 React 或重型 UI 库
- 所有图片都有 alt 文本
- 移动端 CTA 按钮可以换行且保持可读
- 最后运行 npm run build

编辑前请先说明实现计划和预计修改的文件。

“先说明计划”很重要。它能让你在动手前发现范围失控，例如 Claude Code 想额外安装动画库、创建 API、加入数据库。作品集第一版的目标是可上线，不是一次性做成大型系统。

可复制的核心代码

先创建项目。如果你在已有仓库中工作，就不要运行创建命令，而是让 Claude Code 读取当前目录结构。

npm create astro@latest my-portfolio
cd my-portfolio
npm run dev

然后创建数据文件。项目描述要写“问题、负责内容、实现方式、结果”，不要只写技术名词。

// src/data/profile.ts
export const profile = {
  name: "Masa Tanaka",
  role: "前端工程师 / Claude Code 落地顾问",
  location: "Tokyo, Japan",
  summary:
    "我使用 Astro、React、TypeScript 和内容运营方法，构建速度快、易维护、能持续改进的网站。",
  skills: ["Astro", "TypeScript", "React", "CSS", "SEO", "Content Ops"],
  links: {
    email: "masa@example.com",
    github: "https://github.com/example",
  },
} as const;

export const projects = [
  {
    title: "预约网站转化路径优化",
    description:
      "重整移动端菜单、服务说明和预约按钮，让访客更快找到下一步。",
    image: "/projects/booking-site.webp",
    alt: "带有清晰服务卡片和预约按钮的网站截图",
    tags: ["Astro", "SEO", "Responsive"],
    url: "https://example.com/booking",
  },
  {
    title: "SaaS 任务仪表盘",
    description:
      "重新设计任务卡片、筛选器和空状态，让试用用户更容易理解流程。",
    image: "/projects/task-dashboard.webp",
    alt: "带有任务卡片和状态筛选器的 SaaS 仪表盘截图",
    tags: ["TypeScript", "UI Design", "Dashboard"],
    url: "https://example.com/dashboard",
  },
] as const;

页面文件如下。第一版使用邮件链接，不急着做后端表单。等真正有访问量后，再把表单、反垃圾、分析事件拆成独立任务。

---
import { profile, projects } from "../data/profile";
import "../styles/global.css";
---

<html lang="zh">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{profile.name} | Portfolio</title>
    <meta name="description" content={`${profile.role} 的项目、服务和联系方式。`} />
    <meta property="og:title" content={`${profile.name} | Portfolio`} />
    <meta property="og:description" content={profile.summary} />
    <meta property="og:image" content="/ogp.png" />
  </head>
  <body>
    <main>
      <section class="hero" aria-labelledby="hero-title">
        <p class="eyebrow">{profile.location}</p>
        <h1 id="hero-title">{profile.name}</h1>
        <p class="lead">{profile.summary}</p>
        <div class="actions">
          <a class="button primary" href="#projects">查看项目</a>
          <a class="button secondary" href={`mailto:${profile.links.email}`}>开始咨询</a>
        </div>
      </section>

      <section id="projects" class="section" aria-labelledby="projects-title">
        <h2 id="projects-title">Projects</h2>
        <div class="project-grid">
          {projects.map((project) => (
            <article class="project-card">
              <img src={project.image} alt={project.alt} width="960" height="540" loading="lazy" />
              <div class="project-body">
                <h3>{project.title}</h3>
                <p>{project.description}</p>
                <ul class="tag-list">
                  {project.tags.map((tag) => <li>{tag}</li>)}
                </ul>
                <a href={project.url} target="_blank" rel="noreferrer">查看详情</a>
              </div>
            </article>
          ))}
        </div>
      </section>
    </main>
  </body>
</html>

最后加一点 CSS，保证移动端按钮不会挤在一起。

/* src/styles/global.css */
:root {
  --bg: #f7f3ec;
  --panel: #ffffff;
  --text: #1f2933;
  --muted: #5f6c7b;
  --accent: #0f766e;
  --line: #d8dee4;
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Inter, system-ui, sans-serif;
  background: var(--bg);
  color: var(--text);
  line-height: 1.75;
}

.hero,
.section {
  width: min(1120px, calc(100% - 32px));
  margin: 0 auto;
}

.hero {
  min-height: 82vh;
  display: grid;
  align-content: center;
}

.actions,
.tag-list {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  padding: 0;
  list-style: none;
}

.button {
  display: inline-flex;
  min-height: 44px;
  align-items: center;
  justify-content: center;
  padding: 0 18px;
  border-radius: 6px;
  border: 1px solid var(--accent);
  text-decoration: none;
  font-weight: 700;
}

.button.primary {
  background: var(--accent);
  color: white;
}

.project-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 24px;
}

.project-card {
  background: var(--panel);
  border: 1px solid var(--line);
  border-radius: 8px;
  overflow: hidden;
}

.project-card img {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
  display: block;
}

@media (max-width: 640px) {
  .button {
    width: 100%;
  }
}

三个以上真实使用场景

作品集的读者不同，页面重点也不同。

场景	读者想确认	页面应包含
求职或副业申请	技术范围、职责、成果	技术栈、负责范围、演示链接、GitHub
自由职业接单	是否能解决具体业务问题	服务项目、常见咨询、邮件 CTA、交付样例
演讲或写作邀约	专业主题和可信度	主题列表、文章链接、短简介、头像
学习记录	成长过程和可复现项目	学习日志、失败记录、Demo、下一步计划

如果你的目标是接小型网站项目，Projects 里要突出“客户问题”和“下一步行动”。如果目标是求职，就要说明你在团队中的职责，而不是只列工具。Claude Code 可以帮你把项目卡片改写成“问题、职责、实现、结果”的结构。

ClaudeCodeLab 也用同样思路做变现路径：免费文章建立信任，PDF 或模板降低第一次行动成本，再通过培训和咨询解决具体问题。作品集的 CTA 不应只是“Contact”，而应写清楚可以咨询什么。可以参考培训与咨询页面的写法。

SEO、可访问性和常见坑

SEO 的核心是清楚表达。标题、description、h1、项目描述里自然出现“前端工程师作品集”“Astro 网站制作”“Claude Code 导入支持”等关键词即可，不要堆砌。更完整的优化流程可以看 Claude Code SEO 优化。

上线前让 Claude Code 单独做一次审查：

请从 SEO 和可访问性角度审查这个 Astro 作品集。
只列问题、原因和最小修复建议。
检查 title, description, h1/h2/h3, 图片 alt, 内部链接, 外部链接, CTA 和移动端布局。

常见坑有四个。第一，过度设计：动画很强，但第一屏看不出你是谁。第二，证明太空：只说“会 React”，没有讲解决过什么问题。第三，跳过发布检查：链接坏了、OGP 图没设、移动端按钮溢出。第四，把客户资料、未公开 URL、.env 内容直接交给 AI。真实项目要用脱敏截图或虚构数据。

实测结果与下一步

这套结构最有价值的地方，是把内容数据集中到 src/data/profile.ts。实际维护时，修改文案、替换项目、调整样式可以分开让 Claude Code 处理，审查差异会轻很多。上线前至少运行 npm run build，并在手机宽度检查 Hero、Projects 和 Contact。

作品集上线后不是结束。每次新增项目，都要更新截图、结果描述和 CTA。如果读者没有联系你，优先修改服务说明和首屏文案，而不是继续堆动画。小步迭代，才是 Claude Code 最适合发挥价值的方式。

用 Claude Code 和 Astro 搭建作品集网站：从需求到上线检查

先明确作品集要替你完成什么任务

最小可发布结构

让 Claude Code 先给计划

可复制的核心代码

三个以上真实使用场景

SEO、可访问性和常见坑

实测结果与下一步

免费 PDF: Claude Code 速查表

把 Claude Code 变成真正能带来结果的工作流

相关文章

从Obsidian到CLAUDE.md的Claude Code流程：不再反复解释上下文

Claude Code 收入 CTA 路由：从文章分流到 PDF、Gumroad 与咨询

Claude Code 团队交接规则: 把审查证据、权限、回滚和收入路径一起交付