常见错误

约 2826 字大约 9 分钟

2025-11-21

本页面收录了使用Mizuki主题时可能遇到的常见错误及其解决方法，帮助您快速定位并解决问题。

页面404错误专题

Q: 为什么访问页面会显示404错误？

A: 404错误是最常见的问题之一，可能由以下多种原因导致：

1. 部署环境配置问题

Base路径配置错误
- 当部署到子目录时，必须正确设置 base 路径
```
// astro.config.mjs
export default defineConfig({
  // 部署到 https://username.github.io/repo/ 需要设置
  base: '/repo/',
  // 其他配置...
})
```
- GitHub Pages自动部署通常不需要设置base路径
- 自定义域名部署时，确保base设置为 '/'
部署平台路由配置
- 某些平台需要额外配置路由规则
- Vercel/Netlify通常自动处理，但有时需要自定义 vercel.json 或 netlify.toml
- GitHub Pages可能需要 _config.yml 配置
```
# GitHub Pages _config.yml
plugins:
  - jekyll-sitemap
include:
  - _redirects
```

适配器(Adapters)配置

确保使用了正确的Astro适配器

// astro.config.mjs
import vercel from '@astrojs/vercel/server';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
  // 其他配置...
})

2. 本地开发环境问题

文件路径问题
- Astro路由基于文件系统，确保文件名和目录正确
- 动态路由需要正确的参数格式，如 [slug].astro
- 确保文件扩展名为 .astro（而不是 .md）
路由冲突
- 检查是否有多个文件映射到同一路由
- 静态路由优先于动态路由
- 确保没有不正确的索引文件（如多个 index.astro）

3. 构建和部署问题

构建输出不完整
```
# 确保构建成功且没有错误
pnpm build
# 检查dist目录结构是否符合预期
```
- 检查 dist 目录是否包含所有必要文件
- 某些文件可能因构建错误而未被生成
服务器配置问题
- 服务器需要正确配置以处理Astro路由
- 对于SSR模式，确保服务器支持Node.js环境
- 对于SSG模式，确保所有静态资源可访问
缓存问题
- 浏览器缓存可能显示旧的错误页面
- CDN缓存可能延迟更新
- 尝试强制刷新(Ctrl+F5)或清除缓存

4. 特殊场景排查

多语言站点
- 国际化路由需要正确配置
- 确保语言前缀路由正确映射到文件

自定义404页面

可以创建自定义404页面提升用户体验

---
// src/pages/404.astro
---
<html lang="en">
<head>
  <title>404 - 页面未找到</title>
</head>
<body>
  <h1>404 - 页面未找到</h1>
  <p>抱歉，您访问的页面不存在。</p>
</body>
</html>

API路由问题
- API路由可能与其他路由冲突
- 确保API路由位于正确的目录结构中

Q: 如何系统性排查404错误？

A: 按以下步骤系统性排查：

本地环境测试

# 清除构建缓存
pnpm run clean

# 重新构建
pnpm build

# 本地预览构建结果
pnpm preview

检查路由映射
- 使用Astro路由调试工具
- 检查是否有未预期的路由重写
审查部署日志
- 查看部署平台的构建日志
- 检查是否有错误或警告

验证文件结构

# 检查dist目录内容
ls -la dist/
# 确认关键文件存在
find dist/ -name "*.html" | head -10

测试特定路由
- 尝试访问不同的路由，确定404是全局问题还是特定路由
- 检查子页面是否正常工作

Q: 不同部署平台的404错误特殊处理

A: 各平台的特殊处理方式：

Vercel
- 通常自动处理路由，无需额外配置
- 对于SSG项目，确保 vercel.json 正确配置
```
{
  "cleanUrls": true,
  "trailingSlash": false
}
```
Netlify
- 可能需要 _redirects 文件处理SPA路由
```
/*    /index.html   200
```
GitHub Pages
- 确保仓库设置正确
- 检查是否使用正确的分支(GitHub Actions部署时)
- 可能需要 .nojekyll 文件
Cloudflare Pages
- 检查构建设置是否正确
- 可能需要自定义 _redirects 文件
自托管服务器
- 确保服务器配置正确处理路由
- Nginx/Apache需要适当的重写规则

图片相关问题

Q: 为什么图片路径正确但无法显示？

A: 这是最常见的问题之一，通常由以下原因导致：

路径格式不正确

public 目录下的图片应以 / 开头：/images/example.jpg
src 目录下的图片无需 / 开头：src/assets/example.jpg

// 正确写法
images: ["/images/diary/test.webp"] // public目录

// 错误写法
images: ["images/diary/test.webp"] // 缺少开头斜杠

文件名大小写不匹配
- 服务器通常区分大小写，确保文件名与引用完全一致
- 建议：统一使用小写字母和连字符命名
文件扩展名错误
- 检查实际文件扩展名是否与引用一致
- 特别注意 .jpeg 和 .jpg 的区别

Q: 图片在本地正常但部署后显示404？

A: 通常由部署环境配置问题导致：

静态资源未正确部署
- 确保 public 目录内容包含在部署包中
- 检查部署平台是否需要额外配置静态资源路径
部署后路径变化
- 部署到子目录时，可能需要修改 base 配置
- 某些平台会自动添加路径前缀
缓存问题
- 清除浏览器缓存后重试
- 检查部署平台是否有缓存设置

Markdown 渲染问题

Q: 为什么自定义样式没有生效？

A: 检查以下几点：

样式文件位置
- 自定义CSS应放在 src/styles/global.css 或类似位置
- 确保在Astro布局文件中正确引入
样式优先级
- 主题样式可能覆盖自定义样式
- 使用更高优先级的选择器或 !important（谨慎使用）
构建后样式丢失
- 确保样式文件被正确导入到构建流程
- 检查样式文件语法是否有错误

Q: 为什么数学公式不显示或显示异常？

A: 数学公式需要特殊配置：

缺少KaTeX依赖
```
npm install katex
# 或
pnpm add katex
```
配置问题
- 确保 astro.config.mjs 中启用了数学公式支持
- 检查Markdown中的公式语法是否正确
与代码块冲突
- 公式中的 $ 符号可能与代码块语法冲突
- 尝试使用不同语法表示公式

页面布局问题

Q: 为什么侧边栏不显示？

A: 侧边栏显示需要满足特定条件：

配置问题
- 检查 src/config.ts 和 astro.config.mjs 中的配置是否正确

文件路径不匹配

<!-- notes.ts 中配置 -->
link: '/Basic-Layout/'

<!-- 文件中的 permalink -->
permalink: '/Basic-Layout/site-config/' <!-- 正确 -->

目录结构问题
- 确保文件位于配置的目录中
- 检查文件名和目录名是否匹配配置

Q: 为什么导航栏显示异常？

A: 导航栏配置常见问题：

图标未加载
- 确保使用了支持的图标集（如 ri: 图标集）
- 检查图标名称是否正确
链接失效
- 验证链接路径是否正确
- 相对路径需要与当前页面位置匹配
配置格式错误
- 检查配置文件中的语法是否正确
- 确保所有必要的引号和逗号都已添加

构建与部署问题

Q: 为什么本地构建正常但部署后页面404？

A: 通常由以下原因导致：

Base路径配置

部署到子目录时，需要修改 base 配置

// 部署到 https://username.github.io/repo/
export default defineConfig({
  base: '/repo/',
  // 其他配置...
})

路由模式问题
- Astro需要适配器(Adapters)处理SSG/SSR路由
- 部署平台可能需要特殊配置（如 _redirects 文件）
资源路径问题
- 相对路径在部署环境中可能失效
- 使用绝对路径或动态路径配置

Q: 为什么部署后样式丢失？

A: 常见原因及解决方案：

资源未正确部署
- 确保 dist 目录内容全部上传
- 检查服务器是否正确设置静态资源MIME类型
CDN或缓存问题
- 清除CDN缓存
- 禁用浏览器缓存进行测试
路径配置错误
- 检查 base 配置是否与部署路径匹配
- 确保资源使用正确的引用路径

配置相关问题

Q: 为什么配置更改后不生效？

A: 检查以下几点：

配置文件位置
- 确保修改了正确的配置文件（通常是 astro.config.mjs）
- 有些配置可能在 src/config.ts 或其他文件中
开发服务器未重启
- 修改某些配置后需要重启开发服务器
```
# 停止当前服务器 (Ctrl+C)
# 然后重新启动
pnpm dev
```
配置语法错误
- 检查TypeScript语法是否正确
- 使用IDE检查配置文件是否有错误提示

Q: 为什么主题选项不生效？

A: 主题配置常见问题：

配置层级错误

// 正确 (astro.config.mjs)
export default defineConfig({
  integrations: [
    mizuki({
    // 主题配置放在这里
    })
  ]
})

// 错误
export default {
  // 主题配置不应放在这里
}

配置版本不匹配
- 确保主题版本与配置文档匹配
- 新版本可能已弃用某些选项
配置被覆盖
- 检查是否有多个配置文件相互冲突
- 确认加载顺序是否正确

性能问题

Q: 为什么网站加载速度很慢？

A: 优化建议：

大文件优化
- 压缩图片（使用WebP格式）
- 减少不必要的JavaScript和CSS
资源加载优化
- 启用Gzip压缩
- 配置适当的缓存策略
第三方资源
- 检查是否有加载缓慢的外部资源
- 考虑使用CDN加速

Q: 为什么内存使用过高？