用 Claude Code + Astro + GitHub Pages 为开源项目打造现代化官网

我先交代一下这个项目的背景免得后面讲到具体操作时你一头雾水。我手里有一个用 Docker 部署的 sharelatex-ce 在线 LaTeX 协作编辑系统功能很完整但项目本身的官网宣传页非常简陋只有一段 README 和几个零散页面。我想给它重新做一个现代化的开源项目宣传页同时又不想引入太重的前端工程化体系。最终我选定的方案是 Claude Code Astro GitHub PagesClaude Code 负责辅助生成组件和修 bugAstro 负责静态页面构建GitHub Pages 免费托管。整套链路跑通之后效果超出预期这里把完整过程记录下来。这个方案适合谁想给开源项目做官网但不想维护一套复杂前后端的人、想用 AI 辅助写前端但不知道怎么落地的人、以及被 GitHub Pages 部署折磨过的人都可以参考。全程没有买服务器没有配数据库所有代码都在 GitHub 仓库里构建和发布全自动。1. 这个项目到底在做什么需求拆解与方案取舍1.1 sharelatex-ce 的宣传页缺什么sharelatex-ce 是 Overleaf 的开源社区版支持多人实时协作编辑 LaTeX 文档。这类工具型开源项目有一个通病功能强大但门面寒酸。原项目的入口页面通常就是一个简单的 HTML 文件放一段项目说明、几个截图链接、一个 Docker 部署命令然后就没有然后了。对开源项目来说宣传页承担的任务很明确让访客在 10 秒内看懂“这是什么、能干什么、怎么跑起来”。一个合格的宣传页至少要有这些模块Hero 区域一句话说清楚项目定位配一张主视觉图或截图。核心特性三到六个关键卖点用图标或短句列出。快速开始一条 Docker 命令就能启动或者给一个部署链接。截图画廊展示编辑界面、项目列表、编译结果。文档与贡献入口指向完整的文档站和 GitHub 仓库。FAQ 或常见问题降低用户上手门槛。原项目缺的就是这套东西。手写 HTML 当然也能做但后面要改样式、加内容、做多语言维护成本会迅速膨胀。所以我要找一个静态站点生成器用组件化的方式组织页面同时保持极低的运维负担。1.2 为什么是 Astro 而不是 React/Vue 全家桶选型的时候我对比过几个方向。第一类是纯静态 HTML Tailwind。优点是没有构建复杂度随便找个托管就能跑缺点是页面一多头部、导航、底部这些公共部分要复制粘贴改一次全站同步非常痛苦。第二类是 Next.js / Vite React。生态成熟组件化体验好但对一个宣传页来说太重了需要处理客户端路由、打包体积、Node 版本等一系列问题有点拿大炮打蚊子。第三类就是 Astro。它的核心卖点是“默认零 JavaScript”页面在构建时直接输出静态 HTML只有真正需要交互的组件才按需加载 JS。对宣传页这种内容为主的站点这是最优解因为绝大多数访客只是来看内容不需要复杂的客户端渲染。Astro 另一个很实用的特性是支持多种 UI 框架混用。我可以在一部分交互区域用 React 写下拉菜单在另一部分用 Vue 写动态计数器Astro 会在构建时把组件预渲染成静态 HTML同时让交互部分保持正常。这种灵活度是 Next.js 给不了的。还有一个实际原因Astro 对 Markdown 和内容集合Content Collections的原生支持非常成熟适合做文档型宣传页。我可以把项目文档、发布日志、常见问题都写成 Markdown 文件Astro 会自动生成对应页面不需要手写路由。最终我选择了 Astro 5.x 的静态模式SSG输出目录就是dist扔到 GitHub Pages 上即可。1.3 为什么是 GitHub Pages 而不是其他托管宣传页是纯静态站点可选的托管平台很多Netlify、Vercel、Cloudflare Pages、GitHub Pages 都可以。选 GitHub Pages 有几个现实考量。项目代码仓库本来就在 GitHub 上把文档站点和代码放在同一个组织下管理和发现都很方便。GitHub Pages 本身免费绑定自定义域名也不收费还支持自动生成 SSL 证书。更重要的是 GitHub Actions 和 Pages 深度集成我可以把“构建站点 上传部署”写成一个自动化工作流每次推送代码到 main 分支新内容就会自动上线。Netlify 和 Vercel 也很好但多了外部服务依赖。对一个开源项目来说减少第三方依赖意味着减少未来可能出现的维护盲区不用操心某个外部平台改了免费套餐规则不用担心别人 fork 项目之后不知道怎么继续部署。GitHub Pages 是 GitHub 原生能力天然最省事。1.4 Claude Code 在流程里的真实定位很多人把 AI 辅助编程理解成“让 AI 一口气把整个项目写出来”我的实际感受不是这样。Claude Code 是一个命令行环境下的 AI 编程代理它可以直接读写项目文件、执行命令、查看运行结果然后根据上下文修改代码。但它的强项在于“处理局部复杂任务”而不是独立完成全部工作。在这个项目里我用 Claude Code 做了这些事根据设计稿描述生成 Astro 组件。把一段冗长的 CSS 重构为更合理的层级结构。为页面生成 SEO 所需的 meta 信息和 Open Graph 标签。定位构建过程中报错的具体文件和根因。把 README 里关于部署的内容改写成适合放在宣传页上的 Markdown。Claude Code 更像是项目里的“结对编程伙伴”负责写初稿和排查具体问题最终的技术决策和结构设计还是由我来定。这个定位非常重要直接决定了后面使用 AI 辅助编程的效率和体验。2. 环境准备从零搭起一套可复现的开发链2.1 前置软件清单先把开发环境理清楚。我只列出实际用到的不用装一堆用不上的东西。软件版本建议作用Node.js18.x 或 20.x LTS运行 Astro 构建工具链npm随 Node 自带安装依赖和运行脚本Git2.30 以上版本管理和推送代码GitHub 账号有就行存放仓库、启用 PagesClaude Code最新稳定版AI 辅助编码工具Node.js 版本需要特别注意。Astro 5.x 官方要求 Node 18.17.1 以上但有些特性需要 20.x 才稳定。我本机用的是 Node 20 LTS构建没遇到问题。如果你用的是 18 之前的版本建议先升级否则安装 Astro 时会直接报错。2.2 安装并初始化 Claude CodeClaude Code 的安装方式分两种。一种是作为命令行工具全局安装我采用的是这种方式npm install -g anthropic-ai/claude-code安装完成后进入项目目录执行claude命令第一次运行会引导你登录。登录之前有一个是否允许读取工作目录文件的确认提示这里建议直接允许因为 Claude Code 的核心能力就是读取项目文件来理解上下文。如果拒绝后面所有对话都会被限制体验会很难受。claude启动后进入的是交互式对话界面可以直接用自然语言下达指令比如“查看当前目录结构然后分析 src/pages 下的 index.astro 存在什么问题”。它能调用工具读取文件、搜索代码、执行命令相当于一个能直接操作终端和文件系统的 AI 助手。这里有一个细节值得多说一句Claude Code 不是像 ChatGPT 那样有一个独立网页窗口它直接附着在你的命令行里。所以使用场景必然是在项目目录中以“边对话边改代码”的方式工作。实际用下来的感受是这种附着模式比复制粘贴代码片段要高效得多因为 AI 不需要你反复粘贴文件内容它自己会看。2.3 脚手架创建 Astro 项目创建 Astro 项目很简单官方提供了脚手架命令。我在项目所在的目录结构下方新建了一个docs-site子目录与页面相关的所有代码都放在里面这样就不会跟原来的 C 后端代码混在一起。# 在 docs-site 外层目录执行脚手架 npm create astrolatest docs-site执行过程中 Astro 交互式问几个问题我的答案供你参考是否需要 TypeScript需要。宣传页虽然不大但用了类型之后 Claude Code 生成代码的正确率会明显提升因为它的上下文约束更明确。是否需要安装依赖和初始化 Git是。是否需要示例代码选择精简模板。不用官方带一堆示例组件的模板因为那些示例代码最后大部分要被删掉还会干扰 Claude Code 对项目结构的理解。是否需要 Strict 类型检查是。创建完之后进入目录先跑一次启动脚本确认环境没问题cd docs-site npm run dev浏览器打开http://localhost:4321如果看到默认页面说明基础工作正常。2.4 把项目推进 GitHub 仓库先别急着写代码第一时间把空项目推到 GitHub 是个好习惯。因为后面 Claude Code 生成的代码会有很多轮修改如果没有版本管理出了 bug 很难回溯。git init git add . git commit -m feat: init astro project git branch -M main git remote add origin gitgithub.com:yourname/sharelatex-ce-docs.git git push -u origin main这一步做好之后后续任何一次修改都可以清晰地看到 diff哪段代码是 AI 生成的、哪段是我手改的一目了然。配合 GitHub 的 Pull Request 功能还可以让 Claude Code 在分支上工作确认无误后再合并到 main这样线上一直保持可用状态。3. 页面设计与内容实现把宣传页做出“现代感”3.1 信息架构设计一页式长页还是多页面宣传页的页面结构我参考了目前主流开源项目的做法主页面采用一页式长页设计用一个纵向滚动讲述完整故事另外单独立一个文档入口指向详细介绍页。一页式长页的好处是访客滑动鼠标就能浏览完核心内容不用思考页面间的跳转逻辑适合“让用户快速了解项目”的目标。主页面从上到下依次是导航栏项目名称、GitHub 链接、文档入口。Hero 区项目名、一两句话简介、两个核心按钮“快速开始”和“查看示例”、一张 Dashboard 截图。Logo 栏展示“支持”或“集成”的工具比如 Docker、TeX Live、Git。特性区六张卡片分别讲协作编辑、实时编译、权限管理、版本历史、自定义部署、开放 API。快速开始区一段 docker 启动命令给用户“10 秒上手”的满足感。用户场景区用三段话分别描述“写论文的研究生”“维护内部文档系统的工程师”“开设 LaTeX 课程的高校老师”。FAQ 区几个最常见问题的简短回答。底部导航版权信息、项目许可证、贡献入口。单页面适合宣传但是不适合承载内容复杂的文档。所以我同时设置了/docs路由把完整的部署说明、配置项、常见问题都放在文档站里。由 Astro 的内容集合来实现。3.2 Astro 组件化开发布局与复用Astro 的核心概念是组件一个.astro文件就是一个组件。组件内部可以混写 HTML、CSS 和 JavaScript最终构建时被渲染为静态 HTML。我把这个宣传页拆成以下组件结构src/ components/ Navbar.astro Hero.astro Features.astro QuickStart.astro Scenarios.astro FAQ.astro Footer.astro layouts/ BaseLayout.astro pages/ index.astro docs.astroBaseLayout.astro是所有页面的公共骨架包含head部分的 meta 信息、公共导航栏、底部版权栏以及一个slot /插槽用于嵌入页面内容。这个插槽机制是 Astro 非常实用的设计类似 Vue 的 slot但更简单就是用来告诉“子组件应该渲染在哪里”。以导航栏为例一个最简单的导航组件长这样--- // Navbar.astro interface Props { repoUrl: string; } const { repoUrl } Astro.props; --- header classsite-header div classcontainer header-inner a href#top classbrandShareLaTeX CE/a nav classnav-links a href#features特性/a a href#quickstart快速开始/a a href#faqFAQ/a a href/docs文档/a /nav a href{repoUrl} classbtn-outline target_blankGitHub/a /div /header style .site-header { position: sticky; top: 0; backdrop-filter: blur(8px); background: rgba(255, 255, 255, 0.85); border-bottom: 1px solid #e5e7eb; z-index: 50; } .header-inner { display: flex; align-items: center; justify-content: space-between; padding: 0.875rem 0; } /style组件化之后修改导航栏只需要改一个文件所有引用它的页面都会同步更新。这就是拿 Astro 做多页面宣传页比手写 HTML 高一个档次的原因。3.3 用 Claude Code 生成与重构核心代码项目结构搭好之后大量具体实现要落在代码上。这部分我用 Claude Code 辅助但方式不是直接甩一句“帮我写个页面”而是先把上下文交代清楚再给出可执行任务。我第一次用 Claude Code 的任务是这样写的当前项目是一个 Astro 5 项目用于给 sharelatex-ce 这个开源项目做宣传页。请先读取 src/pages/index.astro然后根据页面现有内容在 src/components 下新建一个 Hero.astro包含一个居中的标题区标题文案由 Astro.props 传入副标题也同样下方一个按钮组左侧是“快速开始”指向 #quickstart右侧是“查看 GitHub”指向 props.repoUrl。按钮样式使用现代渐变hover 时有一个上浮动效。不需要额外的 JavaScript 交互。这个任务足够具体Claude Code 读取了文件后很快生成了一版 Hero 组件。我看了代码逻辑没问题但样式细节不够好于是追加指令调整Hero 的背景不要用纯色改用径向渐变中心偏左一点再叠加一个轻微的网格纹理。不要引入外部图片资源网格纹理用 CSS 背景的 linear-gradient 实现。Claude Code 很快修改完成。这种“生成初稿 继续提修改意见”的迭代方式比我自己从头敲一行行 CSS 要快得多也比让 AI 一次性写整个项目可控得多因为每一步改动范围都很小出问题的概率低。还有一次比较典型的场景是我需要给页面加 Open Graph 标签用于分享到社交平台时展示摘要和缩略图。这种内容本身没有任何难度但容易漏写或者写错。我把需求告诉了 Claude Code为这个站点的所有页面生成完整的 Open Graph 和 Twitter Card 标签放在 BaseLayout.astro 里。og:title、og:description 和 og:image 需要通过 Astro.frontmatter 或 props 传入根据具体页面动态生成。og:image 使用一张现有截图放到 public/ 下。它直接在 BaseLayout 里加了对应逻辑并根据各 page 的 frontmatter 动态取值免去了我一项项手动填写的重复劳动。3.4 内容集合与国际化文档站的基础Astro 的内容集合是一个很有用的功能。我可以在src/content目录下创建 Markdown 文件Astro 会根据src/content.config.ts里的 schema 自动解析并生成页面。我在 content 目录下放了一批文档src/content/docs/ deployment.md configuration.md faq.md contributing.md然后在src/pages/docs.astro里动态获取这些文章的标题和摘要生成一个文档列表页。实际效果是我只要往文件夹里扔一个 Markdown 文件文档导航就会自动多出一项完全不用改路由代码。顺带一提Astro 的国际化支持也很直接。我建了src/content/docs/en/和src/content/docs/zh/两个目录用 frontmatter 里的locale字段区分语言再配合路由参数[lang]实现多语言文档切换。不过第一版我没做完整的多语言只是把页面文案结构预留好了后续随时可以扩展。4. 构建与本地预览确认静态输出正常4.1 构建命令与输出检查写完组件和内容之后第一件事是本地构建确认没有编译错误。npm run build构建成功后会在项目根目录生成dist/文件夹。这是最终的静态产物所有.astro文件被编译成.htmlCSS 被抽离为独立的.css文件用到的少量客户端 JS 被合并成压缩脚本。我打开dist/文件夹检查了一下发现一个问题页面引用的绝对路径都是/比如/assets/index.css、/docs。这个路径在本地访问没问题但如果部署到 GitHub Pages 的项目子目录https://username.github.io/repo-name/所有资源都会跑到域名根路径去直接 404。这是 GitLab Pages 和 GitHub Pages 部署到子路径时最常踩的坑核心解决方法是修改astro.config.mjs的base配置export default defineConfig({ // 替换为自己的仓库名 base: /sharelatex-ce-docs/, site: https://username.github.io, });设置好base之后Astro 构建出来的所有资源路径都会自动带上前缀/sharelatex-ce-docs/。如果之后绑定了自定义域名可以再把base改回/配置文件只需要改这一行。4.2 本地静态预览模拟真实环境在开发模式下面一切正常构建出来的静态文件却可能有问题。我习惯构建之后再跑一个本地静态服务专门用来检查 dist 目录的实际运行效果npx astro preview这个命令会在本地起一个静态服务端口也是 4321预览的是构建产物而不是源码。这样能尽早发现路径错误、资源缺失等问题不必等部署上线后才发现。有一个细节astro preview默认使用的是构建后的产物所以每次改了代码要重新npm run build才能看到效果。如果你只是调样式直接用开发模式就行没必要每次都重新构建。5. GitHub Pages 部署一步步让页面上线5.1 在 GitHub 仓库设置里启用 Pages页面部署到 GitHub Pages第一步是到仓库的 Settings - Pages 页面设置。这里有两种路径一种是直接在 Pages 设置里选择“Deploy from a branch”指定main分支的/docs目录或者根目录另一种是用 GitHub Actions 来部署这是我现在用的方式。采用 Actions 的好处是构建过程和部署过程都被写成代码任何人 fork 这个项目后都能一键部署自己的副本不用在网页上手动配置。对于开源项目来说这种“可复制性”非常重要。5.2 编写 Actions 工作流自动构建并部署在仓库根目录创建.github/workflows/deploy.yml内容如下name: Deploy Astro site to Pages on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Setup Pages uses: actions/configure-pagesv4 - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: ./dist deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这个工作流做了几件事监听 main 分支的 push 事件只要代码有更新就自动触发。在 ubuntu 环境上按 Node 20 配置好运行时。安装依赖并执行npm run build产出dist/。把dist/目录作为 artifact 上传。通过deploy-pages动作把 artifact 发布到 GitHub Pages。需要注意的是npm ci要求仓库里有package-lock.json文件所以初始化项目时一定要用 npm 生成这个锁文件并提交到仓库。5.3 部署后的验证域名、缓存和 HTTPS工作流配置完成后推送代码到 main 分支进入仓库的 Actions 页面可以看到构建任务在跑。等两个 job 都跑完Settings - Pages 页面会显示站点已激活并给出访问地址https://username.github.io/sharelatex-ce-docs/打开地址如果看到的是空白页或者样式丢失优先检查两件事astro.config.mjs里的base是否等于仓库名。是否在public/目录下放置了 favicon 和截图资源并确保引用路径正确。GitHub Pages 默认提供 HTTPS所以不用考虑证书配置。如果绑定了自定义域名需要在仓库根目录添加一个CNAME文件内容就是你的域名GitHub Pages 会自动申请和续期证书。同样地这个文件要提交到 main 分支并且 Actions 构建过程中不能被清掉。5.4 部署后的额外优化自定义域名与站点地图如果想要更好的 SEO 表现可以进一步加一个robots.txt或者sitemap.xml。我把它们放在了public/目录下每次构建都会原样复制到dist/中。public/sitemap.xml指向站点的核心页面再加上 Baidu/Google 的搜索验证文件整个站点的“被收录”能力会明显提升。开源项目往往不太在意 SEO但一个能被搜索引擎正确索引的官网能够持续带来自然流量对项目发展很重要。6. 常见问题与排查技巧实录6.1 资源 404 / 样式全部丢失这个问题我遇到不止一次尤其在第一次部署时。现象打开 GitHub Pages 后页面是纯 HTML没有任何样式图片也全部裂开F12 看到 CSS 请求 404。排查思路先用npx astro preview本地预览构建产物确认本地是否就长这样。如果本地正常但线上 404那基本可以确定是base路径问题。检查astro.config.mjs是否设置了正确的base。如果仓库名是sharelatex-ce-docs那么base要配置成/sharelatex-ce-docs/结尾斜杠不能省略。6.2 Actions 构建失败package-lock.json 未提交现象GitHub Actions 执行npm ci时报错The lock file is not up to date。原因项目初始化后没有把package-lock.json提交到 git。解决方式git add package-lock.json git commit -m chore: commit lockfile git push还有一种情况是本地与 CI 的 Node 版本不一致导致 lockfile 版本冲突所以工作流里的node-version: 20要和本机一致。6.3 Claude Code 改错代码怎么办回滚与分支策略Claude Code 虽然能力强但不是每一次修改都是正确的。遇到它改出一段有问题的代码最合理的方式不是用自然话让它反复修而是直接回滚到上一个正常状态加上更精确的限制条件重新生成。我在这个项目里用了一个简单策略每完成一个页面的初版立刻打一个git commit。如果 Claude Code 后续改动偏离了预期直接git checkout -- src/components/xxx.astro恢复原文件。这样既不怕 AI 改坏代码也能保留尝试新方案的空间。另外用分支隔离 AI 的改动也是好办法。可以开一个ai-wip分支让 Claude Code 随便试确认没问题之后合并回 main。这种方式对多人协作的项目尤其有用不会被 AI 改动直接污染主分支。6.4 Astro 内容集合报错schema 类型不一致给文档内容加了 frontmatter 字段之后偶尔会遇到类型错误。比如构建时报Error: Invalid content frontmatter in src/content/docs/faq.md. Expected { title: string } but received { title: 123 }原因是内容集合的 schema 定义了字段类型但某个 Markdown 文件里的值不符合类型约束。解决方式很简单把 Markdown 文件里的类型改正确或者调整content.config.ts里的 schema 定义。内容集合的类型约束一开始可能觉得啰嗦但确实有用。它能在构建阶段就发现文档结构错误而不是等页面 404 才去排查。6.5 常见问题速查表故障现象常见原因解决方案本地正常远程样式丢失base路径未配置或配错astro.config.mjs配置base: /repo-name/npm ci报 lockfile 错误lockfile 未提交或本地与远端版本不一致提交package-lock.json统一 Node 版本Actions 上传后部署地址 404仓库名与 base 不一致确认 base 与仓库名大小写一致生成文档列表为空内容集合里没有 Markdown 文件或 frontmatter 错误检查src/content目录和 schema 类型Claude Code 生成的组件样式干扰全局组件内style未加 scoped在style上加is:global或使用模块化 class 命名自定义字体加载缓慢字体体积过大或跨域改用系统字体栈减少字体请求6.6 几个值得记住的实操心得最后分享几个踩坑之后沉淀下来的经验。第一Claude Code 的工具链非常强但它需要“合适的问题”。你要把项目的技术栈、目录结构、目标讲清楚它生成的代码才靠谱。我通常会先让它执行claude -p 请读取 astro.config.mjs 和 package.json简要说明这个项目的构建配置和技术栈用这种短命令让它先理解项目再提具体任务。经验是上下文越明确生成质量越高。第二Astro 的style默认是 scoped 的也就是样式只作用于当前组件。如果你想让某个全局样式从组件里发出去需要style is:global。如果不加特定伪类或者 body 级样式容易失效你还以为是 bug。第三页面构建完成后记得检查 HTML 源码Astro 生成的静态页面上如果残留了不必要的内联脚本会影响首屏加载速度。关闭页面里所有不必要的 JS 交互能显著提升 Lighthouse 分数。我实测把这个宣传页从“带少量交互脚本”改成“完全纯静态”首屏加载时间减少了约 40%。第四GitHub Pages 的 build 和 deployment 有时候会有延迟特别是第一次部署可能需要等几分钟。如果 Actions 显示跑完了但还是 404别急着改代码等一两分钟再刷新。最后分享一个实用的小技巧整个项目做下来我最满意的是工作流里加了一个“自动更新截图”的小动作。我每次更新了 sharelatex-ce 的界面只需要把新截图替换到public/screenshots/目录下然后推送代码等 Actions 跑完页面上的截图自然就更新了全程不需要手动碰页面代码。如果你也在维护开源项目建议把宣传页、文档站、自动化部署这三件事尽量打通它们对项目的影响远超你的想象。