我的知识库

Appearance

个人网站部署 ​

本文档记录使用 Vercel 部署个人静态站点的完整流程。

技术栈 ​

  • 框架: VitePress (Vue 3 静态站点生成器)
  • 托管平台: Vercel
  • 身份验证: Vercel Edge Middleware (Basic Auth)

准备工作 ​

1. 创建 GitHub 仓库 ​

bash
# 初始化 git 仓库
git init

# 添加远程仓库
git remote add origin https://github.com/your-username/your-repo.git

# 推送代码
git push -u origin main

2. 本地构建测试 ​

bash
# 安装依赖
npm install

# 构建项目
npm run docs:build

# 本地预览构建结果
npm run docs:preview

Vercel 部署 ​

1. 导入项目到 Vercel ​

  1. 登录 Vercel Dashboard
  2. 点击 "Add New..." → "Project"
  3. 导入你的 GitHub 仓库

2. 配置构建设置 ​

Vercel 会自动检测 VitePress 项目，但也可以手动配置：

json
{
  "buildCommand": "npm run docs:build",
  "outputDirectory": ".vitepress/dist"
}

3. 配置环境变量 ​

在 Vercel Dashboard 中设置环境变量：

变量名说明示例值
BASIC_AUTH_USER登录用户名admin
BASIC_AUTH_PASSWORD登录密码your-secure-password

注意: 请使用强密码，不要使用默认值。

4. Edge Middleware 配置 ​

项目根目录的 middleware.js 文件实现 Basic Auth：

js
import { next } from '@vercel/edge';

export const config = {
  matcher: '/:path*', // 匹配所有路径
};

export default function middleware(request) {
  const authorizationHeader = request.headers.get('authorization');

  if (authorizationHeader) {
    const basicAuth = authorizationHeader.split(' ')[1];
    const [user, pwd] = atob(basicAuth).split(':');

    const targetUser = process.env.BASIC_AUTH_USER || 'admin';
    const targetPwd = process.env.BASIC_AUTH_PASSWORD || 'password';

    if (user === targetUser && pwd === targetPwd) {
      return next();
    }
  }

  return new Response('需要登录才能访问', {
    status: 401,
    headers: {
      'WWW-Authenticate': 'Basic realm="Secure Area"',
    },
  });
}

5. 安装依赖 ​

确保 package.json 中包含必要的依赖：

json
{
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
  },
  "dependencies": {
    "@vercel/edge": "^1.2.2"
  },
  "devDependencies": {
    "vitepress": "^1.6.4"
  }
}

自动部署 ​

配置完成后，每次推送到 main 分支，Vercel 会自动触发构建和部署。

查看部署状态 ​

  1. 在 Vercel Dashboard 查看部署日志
  2. 构建成功后，访问生成的 URL
  3. 首次访问会弹出登录对话框

常用命令 ​

bash
# 本地开发
npm run docs:dev

# 构建生产版本
npm run docs:build

# 预览构建结果
npm run docs:preview

# 清理构建缓存
rm -rf .vitepress/cache

自定义域名 ​

1. 添加域名 ​

  1. 在 Vercel 项目设置中 → "Domains"
  2. 添加你的域名（如 wiki.yourdomain.com）
  3. 根据提示配置 DNS 记录

2. DNS 配置 ​

类型名称值
CNAMEwikicname.vercel-dns.com

常见问题 ​

Q: 构建失败怎么办？ ​

A: 检查以下几点：

  • package.json 中的脚本是否正确
  • 依赖是否正确安装
  • Node.js 版本是否符合要求（需要 18.0+）

Q: 如何取消 Basic Auth？ ​

A: 删除或重命名 middleware.js 文件，然后重新部署。

Q: 如何修改登录凭据？ ​

A: 在 Vercel Dashboard 的环境变量中修改 BASIC_AUTH_USER 和 BASIC_AUTH_PASSWORD，然后重新部署。

Q: 部署后页面 404？ ​

A: 检查：

  • outputDirectory 配置是否正确（应为 .vitepress/dist）
  • 构建是否成功完成

参考资源 ​