教程全程新手友好，无复杂语法，每一步都附具体操作、命令和避坑提示，无需复杂编程基础，跟着走就能完成从本地文件准备到线上部署的全流程，适配所有新手读者。核心目标：从零准备文件 → 推送 GitHub → 部署静态站 → 激活 AI 分身，全程免费、无门槛、可复刻。

一、项目核心信息

1.1 项目定位与亮点

这是一个融合工程背景与 AI Agent 落地实践的个人品牌网站，核心亮点兼顾颜值与实用性，新手复刻后可直接使用：

• 视觉风格：深空科技风，包含土星旋转、霓虹光效、玻璃拟态，适配移动端和 PC 端，颜值拉满；
• 核心功能：静态主页、可更新学习笔记页、作品集展示、可点击联系方式，满足个人品牌展示需求；
• 特色功能：网页内置 AI 分身，访客可直接对话，密钥不暴露前端，安全可靠；
• 额外适配：支持多语言切换、境外链接提示，细节拉满。

1.2 技术栈

项目采用「纯静态站点 + 少量 Node Serverless 接口」的组合，新手无需深入学习框架，只需掌握基础操作即可：

• 前端基础：HTML5、Tailwind CSS（CDN 引入）、原生 JavaScript；
• 部署工具：GitHub Pages（静态站）、Vercel（AI 分身接口）；
• 辅助工具：Git、Node.js（均免费，安装简单）。

1.3 目录结构（提前熟悉，避免文件放错）

复刻前先明确文件结构，后续操作更顺畅，核心目录如下（新手可直接对照搭建）：

.
├─ index.html                 # 主页面（核心静态页面）
├─ notes.html                 # 可更新学习笔记页
├─ images/                    # 图片资源（头像、配图、图标）
├─ docs/                      # 相关文档存放
├─ api/                       # AI分身接口相关
├─ server/                    # 本地代理相关文件
├─ vercel.json                # Vercel部署配置
├─ package.json               # 项目依赖配置
└─ .env.example               # 环境变量示例（本地测试用）

二、前期准备

2.1 安装必备工具

所有工具安装均无需复杂操作，新手直接按指引来，安装完成后验证是否成功：

• Node.js：下载地址 https://nodejs.org/，选择稳定版；安装时勾选「Add to PATH」，安装完成后，打开终端输入 node -v，能显示版本号即成功。
• Git：下载地址 https://git-scm.com/，安装时默认下一步即可；安装完成后，终端输入 git --version，显示版本号即成功。
• GitHub 账号：打开 https://github.com/，注册一个账号，用于存放代码和部署静态站。

2.2 准备核心文件

无需从零编写代码，可直接复用项目核心文件，步骤如下：

• 在本地创建一个文件夹（例如 D:\vienne-ai-site），用于存放所有项目文件；
• 核心文件可直接复用模板，确保文件夹结构与上文「目录结构」一致；
• 重点准备 images 文件夹：放入头像、项目配图、网站图标，文件名建议用英文 / 数字 / 短横线，避免空格和中文（防止路径报错）。

三、本地开发与配置（确保本地能正常运行）

3.1 安装项目依赖

打开终端，进入本地项目文件夹（例如 D:\vienne-ai-site），执行以下命令，安装所需依赖，全程等待即可：

cd D:\vienne-ai-site
npm install

避坑提示：若执行命令报错，大概率是 Node.js 未安装成功或未勾选「Add to PATH」，重新安装 Node.js 并勾选该选项即可。

3.2 配置本地环境变量（仅本地测试用）

环境变量用于本地测试 AI 分身，无需上传到 GitHub，步骤如下：

• 找到项目根目录下的 .env.example 文件，复制一份并重命名为 .env；
• 打开 .env 文件，填写以下核心环境变量（按自己的实际信息填写）：

OPENCLAW_API_KEY=你的密钥
OPENCLAW_CHAT_URL=https://xxx/api/v3/responses
OPENCLAW_MODEL=模型名称
OPENCLAW_MODE=responses

可选补充变量（按需填写）：

OPENCLAW_SYSTEM_PROMPT=AI分身对话提示词
OPENCLAW_OWNER_FACTS=你的个人公开信息
CHAT_PROXY_PORT=8790

重要提示：.env 文件不要提交到 GitHub，避免密钥泄露。

3.3 启动本地服务，测试效果

分两步启动，先启动 AI 分身本地代理，再启动静态站，顺序不要乱：

1. 启动 AI 分身本地代理：终端执行以下命令，启动成功后，访问 http://127.0.0.1:8790/health，若显示 JSON 且 configured: true，则代理启动成功。

npm run chat-proxy

1. 启动本地静态站：打开一个新的终端，进入项目文件夹，执行以下命令，启动成功后，访问 http://127.0.0.1:8765，即可看到本地的个人主页，测试 AI 分身是否能正常对话。

cd D:\vienne-ai-site
npm run site

3.4 配置自检（可选，避免后续部署踩坑）

若本地启动后 AI 分身无法对话，可执行以下命令，自检环境变量和配置是否正确，根据提示修改即可：

npm run verify-chat

四、推送代码到 GitHub（关键步骤，为部署做准备）

将本地项目文件推送到 GitHub，后续部署静态站和 AI 分身都需要依赖 GitHub 仓库，步骤如下，新手直接复制命令执行即可：

4.1 创建 GitHub 仓库

登录 GitHub，点击右上角「+」→「New repository」，设置如下：

• 仓库名称：建议填写 vienne-ai-site（与本地文件夹名称一致，便于记忆）；
• 权限：勾选「Public」（免费）；
• 不要勾选「Add a README file」，点击「Create repository」。

4.2 绑定远端仓库并推送代码

打开本地终端，进入项目文件夹，依次执行以下命令，每一步执行完成再进行下一步：

cd D:\vienne-ai-site
git init
git branch -M main
git remote add origin https://github.com/你的GitHub用户名/你的仓库名.git

4.3 创建 .gitignore 文件（避免提交无用文件）

创建 .gitignore 文件，用于忽略不该提交的文件（如密钥文件、依赖文件夹），避免泄露信息：Windows 终端执行：

powershell

@"
node_modules/
.env
.env.txt
server/owner-facts.txt
"@ | Out-File -Encoding utf8 .gitignore

Mac 终端执行：

echo -e "node_modules/\n.env\n.env.txt\nserver/owner-facts.txt" > .gitignore

4.4 提交并推送代码

git add .
git commit -m "init: add vienne-ai-site project"
git push -u origin main

避坑提示：推送时若需要登录 GitHub，按提示输入账号密码或令牌即可；推送完成后，打开 GitHub 仓库，能看到所有项目文件，即推送成功。

五、部署静态站（GitHub Pages，免费上线页面）

GitHub Pages 可免费部署静态站，让所有人都能访问你的个人主页，步骤简单，新手直接按指引操作：

1. 打开 GitHub 仓库 → 点击右上角「Settings」；
2. 左侧菜单找到「Pages」，点击进入；
3. 在「Build and deployment」板块，设置以下参数：
   • Source：选择「Deploy from a branch」；
   • Branch：选择「main」；
   • Folder：选择「/(root)」；
4. 点击「Save」，等待 1-2 分钟，GitHub 会生成一个访问地址；
5. 访问该地址，若能看到个人主页和学习笔记页，且图片能正常显示，说明静态站部署成功。

5.1 静态站部署避坑汇总

• 若 notes.html 打开 404：随便修改一下 index.html（比如加一行注释），提交到 GitHub，等待 1-2 分钟再刷新即可；
• 若图片无法显示：检查图片路径是否为相对路径，不要用本地盘符路径，且图片已推送到 GitHub；
• 若页面样式错乱：检查 index.html 中 Tailwind CSS 的 CDN 链接是否正确，确保网络能正常访问 CDN。

六、部署 Vercel（激活 AI 分身，让对话功能可用）

GitHub Pages 仅能部署静态页面，AI 分身需要依赖 Serverless 接口，Vercel 可免费部署该接口，步骤如下：

6.1 部署前准备（1 分钟检查）

• 确认 GitHub 仓库的 main 分支中，有以下文件：api/chat.js、api/health.js、server/chat-handler.mjs、vercel.json、package.json；
• 确认 GitHub 仓库中没有 node_modules 文件夹（若有，删除后重新推送代码）。

6.2 导入项目到 Vercel

1. 打开 Vercel 官网 https://vercel.com/，用 GitHub 账号登录；
2. 登录后，点击右上角「Add New」→「Project」；
3. 选择「Import Git Repository」，找到自己的 vienne-ai-site 仓库，点击「Import」；
4. 配置项目参数（新手默认即可）：
   • Branch：选择「main」；
   • Application Preset：选择「Other」；
   • Root Directory：保持 ./；

6.3 设置环境变量（关键，AI 分身能否运行全看这个）

在 Vercel 项目配置页面的下方，找到「Environment Variables」板块，添加以下核心变量：

1. 点击「Add More」，添加 3 个必填变量（Key 必须一模一样，注意大小写）：
   • Key：OPENCLAW_API_KEY，Value：填写你的密钥；
   • Key：OPENCLAW_CHAT_URL，Value：填写上游模型的对话地址；
   • Key：OPENCLAW_MODEL，Value：填写模型名称；
2. 可选添加：OPENCLAW_MODE、OPENCLAW_SYSTEM_PROMPT、OPENCLAW_OWNER_FACTS；
3. 勾选环境变量适用范围：勾选「Production」；
4. 点击「Save」，保存环境变量。

重要提示：不要将 .env 文件提交到 GitHub，若密钥泄露，需立即在模型控制台轮换密钥。

6.4 部署并自检

1. 点击页面最下方「Deploy」，开始部署，等待 1-2 分钟；
2. 部署完成后，Vercel 会生成一个线上地址，点击该地址，进入个人主页；
3. 部署后自检（必做）：
   • 访问 https://你的Vercel域名/api/health，若显示 JSON 且 configured: true，说明接口部署成功；
   • 打开 Vercel 生成的主页，点击 AI 分身，输入一句话，若能正常收到回复，说明 AI 分身激活成功；
   • 若修改了环境变量，需回到 Vercel 项目详情页，找到对应的部署记录，点击「Redeploy」生效。

七、常见问题与避坑汇总（新手必看）

整理了新手复刻过程中最常遇到的问题，对照排查，无需额外找解决方案：

• Vercel 报错「FastAPI entrypoint」：确认 Application Preset 选的是「Other」，且 vercel.json 文件已推送到 GitHub main 分支；
• 报错「The pattern "api/chat.js" doesn’t match any Serverless Functions」：检查 GitHub main 分支中是否有 api/chat.js 文件；
• /api/chat 返回 503：环境变量未配全，访问 /api/health 查看 configured 是否为 true；
• /api/chat 返回 502：上游模型的 URL 或模型名称不匹配，核对 .env 和 Vercel 环境变量；
• GitHub Pages 图片 404：图片路径错误或文件未推送到 GitHub，检查图片路径为相对路径；
• 本地 AI 分身正常，线上无法使用：Vercel 环境变量未配置或配置错误，重新检查并 Redeploy。

八、安全注意事项

• 禁止提交到 GitHub 的文件：.env、node_modules/、server/owner-facts.txt（避免隐私和密钥泄露）；
• 若密钥不慎暴露，需立即在模型控制台轮换密钥，防止被滥用；
• 线上部署后，定期访问 /api/health 自检，确保 AI 分身正常可用。

九、总结

到这里，你的 AI 个人主页就已经完全上线了 —— 既有深空科技风的美观页面，又有可对话的 AI 分身，全程免费、零门槛、可复刻，新手也能轻松完成。后续可根据自己的需求，修改 index.html 中的个人信息、作品集内容，更新 notes.html 中的学习笔记，持续完善个人品牌网站。如果遇到问题，可对照「常见问题」排查，或留言咨询。

网站链接：Vienne-AI Site

项目链接：https://github.com/vienne53/vienne-ai-site