1. 依赖安装失败#

症状：

• npm install 失败
• 依赖冲突
• 网络错误

解决方案：

1
# 清除缓存
2
npm cache clean --force
3

4
# 重新安装
5
tnpm install
6

7
# 如果使用 pnpm
8
pnpm install
9

10
# 如果使用 yarn
11
yarn install

常见错误：

• ETIMEDOUT - 网络超时，检查网络连接
• EACCES - 权限不足，使用管理员权限
• ENOTFOUND - 依赖包不存在，检查 package.json

2. 构建命令失败#

症状：

• npm run build 失败
• 构建过程中报错
• 生成的文件不完整

解决方案：

1
# 检查错误信息
2
npm run build
3

4
# 检查 TypeScript 类型错误
5
npm run typecheck
6

7
# 检查代码 lint 错误
8
npm run lint

常见错误：

• 语法错误 - 检查代码语法
• 类型错误 - 检查 TypeScript 类型
• 路径错误 - 检查文件路径

3. 开发服务器启动失败#

症状：

• npm run dev 失败
• 端口被占用
• 依赖缺失

解决方案：

1
# 检查端口是否被占用
2
netstat -ano | findstr :4321
3

4
# 杀死占用端口的进程
5
Taskkill /PID <PID> /F
6

7
# 重新启动开发服务器
8
npm run dev

1. GitHub Pages 部署失败#

症状：

• GitHub Actions 构建失败
• 页面显示 404
• 资源加载失败

解决方案：

1. 检查 GitHub Actions 日志
2. 确认配置文件
3. 检查 base URL

配置示例：

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches:
6
      - main
7

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v3
13
      - uses: actions/setup-node@v3
14
        with:
15
          node-version: 18
16
      - run: npm install
17
      - run: npm run build
18
      - uses: peaceiris/actions-gh-pages@v3
19
        with:
20
          github_token: ${{ secrets.GITHUB_TOKEN }}
21
          publish_dir: ./dist

2. Vercel 部署失败#

症状：

• 构建失败
• 环境变量缺失
• 依赖安装失败

解决方案：

1. 检查构建日志
2. 配置环境变量
3. 调整构建命令

Vercel 配置：

• Framework Preset: Astro
• Build Command: npm run build
• Output Directory: dist
• Install Command: npm install

3. 域名配置问题#

症状：

• 域名无法访问
• SSL 证书错误
• 重定向问题

解决方案：

1. 检查 DNS 配置
2. 确认域名解析
3. 设置 SSL 证书

DNS 记录示例：

• A 记录: @ → 服务器 IP
• CNAME 记录: www → your-username.github.io

1. 页面加载缓慢#

症状：

• 首屏加载时间长
• 图片加载慢
• 脚本执行时间长

解决方案：

1. 图片优化

   • 使用 WebP 格式
   • 压缩图片
   • 懒加载图片

2. 代码优化

   • 代码分割
   • 按需加载
   • 减少第三方脚本

3. 服务器优化

   • 启用 Gzip 压缩
   • 使用 CDN
   • 缓存策略

2. 构建时间过长#

症状：

• npm run build 耗时过长
• 内存使用过高
• 构建过程卡住

解决方案：

1
# 增加内存限制
2
NODE_OPTIONS="--max-old-space-size=4096" npm run build
3

4
# 优化构建配置
5
# astro.config.mjs
6
import { defineConfig } from 'astro/config';
7

8
export default defineConfig({
9
  build: {
10
    minify: true,
11
    inlineStylesheets: 'auto',
12
  },
13
});

3. 运行时性能问题#

症状：

• 页面滚动卡顿
• 交互响应慢
• 内存泄漏

解决方案：

1. 使用浏览器开发者工具

   • Performance 面板分析
   • Memory 面板检查内存
   • Network 面板分析网络请求

2. 代码优化

   • 减少 DOM 操作
   • 使用防抖和节流
   • 优化事件监听器

1. 搜索引擎不收录#

症状：

• 网站在搜索结果中不显示
• 索引状态异常
• 抓取错误

解决方案：

1. 提交站点地图

   • 创建 sitemap.xml
   • 提交到 Google Search Console
   • 提交到 Bing Webmaster Tools

2. 检查 robots.txt

   1
   User-agent: *
   2
   Allow: /

3. 检查页面元数据

   • 标题和描述
   • 结构化数据
   • canonical URL

2. 排名下降#

症状：

• 搜索排名突然下降
• 流量减少
• 关键词排名变化

解决方案：

1. 检查 Google Search Console

   • 查看抓取错误
   • 检查安全问题
   • 分析性能报告

2. 内容优化

   • 更新内容
   • 修复死链接
   • 优化关键词

3. 技术优化

   • 提高页面速度
   • 修复移动友好性
   • 改善用户体验

3. 结构化数据错误#

症状：

• 富摘要不显示
• 结构化数据验证失败
• 搜索结果异常

解决方案：

1. 使用结构化数据测试工具

   • Google 结构化数据测试工具
   • Rich Results Test

2. 修复结构化数据

   1
   {
   2
     "@context": "https://schema.org",
   3
     "@type": "BlogPosting",
   4
     "headline": "文章标题",
   5
     "description": "文章描述",
   6
     "image": "https://example.com/image.jpg",
   7
     "author": {
   8
       "@type": "Person",
   9
       "name": "作者名称"
   10
     },
   11
     "datePublished": "2026-04-24",
   12
     "dateModified": "2026-04-24"
   13
   }

1. 评论系统不工作#

症状：

• 评论框不显示
• 评论提交失败
• 评论数据丢失

解决方案：

1. 检查评论系统配置

   • 确认 API 密钥
   • 检查域名配置
   • 验证权限设置

2. 常见评论系统问题

   • Giscus: 检查 GitHub App 权限
   • Disqus: 确认 shortname 正确
   • Waline: 检查服务端配置

2. 搜索功能不工作#

症状：

• 搜索框不显示
• 搜索结果为空
• 搜索功能无响应

解决方案：

1. 检查搜索配置

   • 确认搜索方法设置
   • 检查索引生成
   • 验证搜索组件

2. PageFind 搜索

   • 确保已运行 npm run build
   • 检查索引文件生成
   • 验证搜索组件配置

3. 图片显示异常#

症状：

• 图片不显示
• 图片加载失败
• 图片变形

解决方案：

1. 检查图片路径

   • 确认相对路径正确
   • 检查文件存在性
   • 验证文件权限

2. 图片格式问题

   • 确认浏览器支持
   • 检查图片编码
   • 测试不同格式

1. Node.js 版本问题#

症状：

• 依赖安装失败
• 构建过程出错
• 运行时错误

解决方案：

1
# 检查 Node.js 版本
2
node -v
3

4
# 使用 nvm 管理版本
5
nvm use 18
6

7
# 或使用 n
8
n 18

推荐版本：

• Node.js 18.x 或 20.x
• npm 9.x 或更高

2. 操作系统兼容性#

症状：

• Windows 特定错误
• Linux 路径问题
• macOS 权限问题

解决方案：

1. Windows

   • 使用 PowerShell 或 WSL
   • 注意路径分隔符
   • 以管理员身份运行

2. Linux/macOS

   • 检查文件权限
   • 使用 bash 或 zsh
   • 安装必要的依赖

3. 网络环境问题#

症状：

• 依赖安装超时
• CDN 资源加载失败
• 外部 API 调用失败

解决方案：

1. 网络连接

   • 检查网络连接
   • 尝试使用 VPN
   • 配置代理

2. 镜像源

   1
   # npm 镜像
   2
   npm config set registry https://registry.npmmirror.com
   3
   
   4
   # yarn 镜像
   5
   yarn config set registry https://registry.npmmirror.com

1. XSS 攻击#

症状：

• 页面注入恶意脚本
• 用户数据泄露
• 会话劫持

解决方案：

1. 输入验证

   • 过滤用户输入
   • 转义特殊字符
   • 使用安全的模板系统

2. Content Security Policy

   1
   <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://trusted-cdn.com;">

2. CSRF 攻击#

症状：

• 未授权的请求
• 账户被恶意操作
• 数据被篡改

解决方案：

1. CSRF 令牌

   • 使用 CSRF 令牌
   • 验证请求来源
   • 检查 Referer 头

2. SameSite Cookie

   1
   res.cookie('session', sessionId, {
   2
     sameSite: 'strict',
   3
     secure: true,
   4
     httpOnly: true
   5
   });

3. 依赖安全漏洞#

症状：

• 依赖包存在漏洞
• 安全扫描失败
• 构建警告

解决方案：

1
# 检查依赖漏洞
2
npm audit
3

4
# 修复漏洞
5
npm audit fix
6

7
# 更新依赖
8
npm update

1. 浏览器开发者工具#

常用功能：

• Console - 查看错误信息
• Network - 分析网络请求
• Elements - 检查 DOM 结构
• Application - 查看存储和缓存
• Performance - 分析性能
• Memory - 检查内存使用

2. 日志分析#

日志位置：

• 构建日志
• 服务器日志
• 浏览器控制台
• 分析工具日志

分析方法：

• 查找错误关键词
• 检查堆栈跟踪
• 定位问题来源
• 重现错误场景

3. 断点调试#

使用 VS Code 调试：

1
{
2
  "version": "0.2.0",
3
  "configurations": [
4
    {
5
      "type": "node",
6
      "request": "launch",
7
      "name": "Debug Astro",
8
      "runtimeExecutable": "npm",
9
      "runtimeArgs": ["run", "dev"],
10
      "console": "integratedTerminal"
11
    }
12
  ]
13
}

1. 预防措施#

• 定期更新依赖
• 备份代码和数据
• 监控网站状态
• 测试功能完整性
• 保持环境一致性

2. 问题排查流程#

1. 复现问题 - 确认问题的具体表现
2. 收集信息 - 查看日志和错误信息
3. 分析原因 - 定位问题的根本原因
4. 尝试解决方案 - 应用可能的解决方法
5. 验证结果 - 确认问题是否解决
6. 记录解决方案 - 为未来参考

3. 工具推荐#

调试工具：

• Chrome DevTools - 浏览器调试
• VS Code Debugger - 代码调试
• Postman - API 测试
• Lighthouse - 性能分析
• PageSpeed Insights - 速度测试

监控工具：

• UptimeRobot - 网站监控
• Google Search Console - SEO 监控
• Sentry - 错误监控
• New Relic - 性能监控

1. 404 错误#

原因：

• 页面不存在
• 路由配置错误
• 链接错误

解决方案：

• 检查 URL 拼写
• 确认页面存在
• 配置 404 页面

2. 500 错误#

原因：

• 服务器内部错误
• 代码异常
• 资源不足

解决方案：

• 检查服务器日志
• 修复代码错误
• 增加服务器资源

3. 403 错误#

原因：

• 权限不足
• 访问被拒绝
• 防火墙阻止

解决方案：

• 检查文件权限
• 验证访问控制
• 调整防火墙设置

4. 429 错误#

原因：

• 请求过于频繁
• API 速率限制
• 服务器限流

解决方案：

• 减少请求频率
• 实现请求队列
• 缓存 API 响应