类视搜图

简体中文

English

简体中文

English

🐛 常见问题排查 ​

双构建开发相关问题 ​

Q1: 运行 npm run dev:en 看到的还是中文网站？ ​

症状:

  • 运行 npm run dev:en 后，浏览器显示的还是中文内容
  • 或者英文站点显示不正确

原因: VitePress 缓存了之前的配置，srcDir 配置在开发模式下需要清除缓存才能生效。

解决方案:

bash
# 步骤 1: 停止当前运行的开发服务器（Ctrl+C）

# 步骤 2: 清除 VitePress 缓存

# Windows (PowerShell)
Remove-Item -Recurse -Force .vitepress\cache

# Linux/Mac
rm -rf .vitepress/cache

# 步骤 3: 重新启动开发服务器
npm run dev:en

验证方法:

  1. 访问 http://localhost:5173
  2. 检查页面标题是否为 "FlareSeek"（而不是"类视搜图"）
  3. 检查导航菜单是否为英文

Q2: 英文站缺少静态资源（图片404）？ ​

症状:

  • 英文站点可以访问
  • 但图片、CSS等静态资源加载失败

原因: /public/ 目录在 /en/ 中不存在

解决方案:

方案1: 使用软链接（推荐，Linux/Mac）

bash
cd en
ln -s ../public public

方案2: 复制目录（Windows）

bash
xcopy /E /I public en\public

方案3: 修改配置共享 public 目录

typescript
// .vitepress/config-en.ts
export default defineConfig({
  // ... 其他配置
  
  // 添加这个配置
  vite: {
    publicDir: '../public'  // 指向根目录的 public
  }
})

Q3: 构建后英文站路径还是 /en/xxx？ ​

症状:

  • 构建后的 dist-en/ 目录中路径包含 /en/
  • 例如：dist-en/en/docs/installation.html

原因: srcDir 配置错误

解决方案:

检查 .vitepress/config-en.ts:

typescript
// ❌ 错误
srcDir: '../en'

// ✅ 正确
srcDir: './en'

Q4: 语言切换后跳转404？ ​

症状:

  • 在中文站点击语言切换
  • 跳转到英文站后显示404

原因: 中英文文件路径不对应

解决方案:

确保中英文文件路径完全一致：

✅ 正确
/docs/installation.md
/en/docs/installation.md

❌ 错误
/docs/installation.md
/en/docs/install.md       # 文件名不一致

Q5: 开发服务器端口被占用？ ​

症状:

Error: Port 5173 is already in use

解决方案:

方案1: 关闭占用端口的进程

bash
# Windows
netstat -ano | findstr :5173
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -i :5173
kill -9 <进程ID>

方案2: 使用不同端口

bash
# 中文站使用 5173
npm run dev:cn

# 英文站使用 5174（修改 package.json）

修改 package.json:

json
{
  "dev:en": "vitepress dev --config .vitepress/config-en.ts --port 5174"
}

Q6: 构建时提示文件找不到？ ​

症状:

Error: ENOENT: no such file or directory

解决方案:

  1. 检查文件是否存在

    bash
    ls en/index.md

  2. 检查 srcExclude 配置

    typescript
    // 确保没有错误排除需要的文件
srcExclude: [
  'docs-internal/**',  // ✅ 正确
  'en/**'              // ❌ 不要在英文配置中排除 en/
]

  3. 检查文件路径大小写

    • Windows不区分，但Linux区分大小写
    • 确保文件名大小写一致

Q7: 构建产物中包含 docs-internal/？ ​

症状:

  • dist-cn/ 或 dist-en/ 中出现了 docs-internal/ 目录

原因: srcExclude 配置缺失或错误

解决方案:

检查配置文件:

typescript
// .vitepress/config-cn.ts 和 config-en.ts
srcExclude: [
  ...(sharedConfig.srcExclude || []),
  'docs-internal/**'    // 必须包含这一行
]

验证:

bash
npm run build:all
ls dist-cn/docs-internal   # 应该显示"找不到"
ls dist-en/docs-internal    # 应该显示"找不到"

Q8: 开发时修改配置不生效？ ​

症状:

  • 修改了 config-cn.ts 或 config-en.ts
  • 但重新加载页面后没有变化

解决方案:

  1. 重启开发服务器

    bash
    # 停止服务器（Ctrl+C）
# 重新启动
npm run dev:cn  # 或 dev:en

  2. 清除缓存

    bash
    rmdir /s /q .vitepress\cache     # Windows
rm -rf .vitepress/cache           # Linux/Mac

  3. 清除浏览器缓存

    • Chrome: Ctrl+Shift+Delete
    • 或使用无痕模式测试

Q9: TypeScript 配置错误？ ​

症状:

Cannot find module '.vitepress/config-cn.ts'

解决方案:

  1. 检查文件扩展名

    bash
    ls .vitepress/config-cn.ts   # 确认文件存在

  2. 检查 TypeScript 配置

    bash
    # 确保安装了依赖
npm install

  3. 检查 VitePress 版本

    bash
    npm list vitepress
# 应该是 1.6.4 或更高版本

Q10: 首页组件不显示？ ​

症状:

  • 英文站首页空白或缺少组件
  • 中文站正常

原因: 组件路径配置问题或 i18n 配置问题

解决方案:

  1. 检查英文首页配置

    markdown
    <!-- en/index.md -->
---
layout: home
---

<FeatureCards />
<SpotlightCard />
<!-- 其他组件 -->

  2. 检查 i18n 配置

    • 确保 useI18n() 能正确识别英文语言
    • 检查翻译文件是否完整

  3. 清除缓存重试

    bash
    rmdir /s /q .vitepress\cache
npm run dev:en

🔍 调试技巧 ​

1. 检查当前配置 ​

在浏览器控制台运行:

javascript
console.log(window.location)
console.log(document.documentElement.lang)

2. 检查构建输出 ​

bash
npm run build:cn
ls -la dist-cn/        # 查看文件结构

npm run build:en
ls -la dist-en/        # 查看文件结构

3. 对比配置差异 ​

bash
# 对比两个配置文件
diff .vitepress/config-cn.ts .vitepress/config-en.ts

4. 验证路径映射 ​

bash
# 检查文件是否存在
ls docs/installation.md
ls en/docs/installation.md

📞 获取帮助 ​

如果以上方法都无法解决问题：

  1. 查看详细文档

  2. 检查配置

    bash
    npm run verify

  3. 提交 Issue

    • 包含错误信息
    • 包含配置文件内容
    • 说明复现步骤

最后更新: 2025-01-10
维护者: 开发团队