---
title: "常见问题"
description: "关于 Movk Nuxt Docs 的常见疑问：与 Nuxt UI 文档模板的关系、包管理器与 Node.js 版本、单语言站点、关闭 GitHub 集成、接入其他 AI 厂商、升级与组件覆盖、静态部署的限制等，每条都链接到详细说明。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/faq"
---
# 常见问题

> 关于 Movk Nuxt Docs 的常见疑问：与 Nuxt UI 文档模板的关系、包管理器与 Node.js 版本、单语言站点、关闭 GitHub 集成、接入其他 AI 厂商、升级与组件覆盖、静态部署的限制等，每条都链接到详细说明。

## 它和 Nuxt UI 的文档模板是什么关系？

Movk Nuxt Docs 源自 [Nuxt UI](https://ui.nuxt.com) 的文档站点与 [UI 文档模板](https://docs-template.nuxt.dev/)，以 Nuxt Layer 的形式发布为 `@movk/nuxt-docs`。在此基础上增加了组件文档自动生成、AI Chat、MCP Server、Agent Skills、多语言与编辑风主题，并定期同步上游的改动。你只需在 `nuxt.config.ts` 中 `extends: ['@movk/nuxt-docs']`，不必复制模板代码。见[简介](https://docs.mhaibaraai.cn/docs/getting-started)。

## 必须使用 pnpm 吗？

不必，pnpm、npm、yarn 与 bun 都可以。环境要求是 Nuxt 4.6.1+（4.x），以及 Node.js 22.22.3+（22.x）、24.15.0+（24.x）或 26+。Nuxt Content 依赖内置的 `node:sqlite`。使用 pnpm 时需要在 `pnpm-workspace.yaml` 中允许 `sharp` 的构建脚本，见[故障排查](https://docs.mhaibaraai.cn/docs/guide/troubleshooting#pnpm-%E5%AE%89%E8%A3%85%E5%90%8E%E5%9B%BE%E7%89%87%E5%A4%84%E7%90%86%E5%A4%B1%E8%B4%A5)。

## 不需要多语言，可以不装 `@nuxtjs/i18n` 吗？

可以，这是默认状态。不配置 `i18n` 时站点按单语言运行，URL 不带语言前缀；界面文案的语言用 `app.config` 的 `i18n.locale` 切换。见[国际化](https://docs.mhaibaraai.cn/docs/guide/i18n#%E5%8D%95%E8%AF%AD%E8%A8%80%E7%AB%99%E7%82%B9)。

## 文档必须放在 `content/docs` 吗？

是的。文档固定位于 `content/docs/`，路由前缀固定为 `/docs`，其他语言放在 `content/{code}/docs/`。首页来自 `content/index.md`，存在 `app/pages/index.vue` 时改用你自己的页面。见[项目结构](https://docs.mhaibaraai.cn/docs/getting-started/project-structure)。

## 如何关闭 GitHub 集成？

在 `app.config.ts` 中把 `github` 设为 `false`，编辑链接、查看源码与提交记录都会隐藏：

```ts [app/app.config.ts]
export default defineAppConfig({
  github: false
})
```

保留集成时，Layer 会从 Git 信息推断仓库，生产环境需要配置 `NUXT_GITHUB_TOKEN`。见[配置](https://docs.mhaibaraai.cn/docs/guide/configuration)。

## 能用 OpenAI 以外的模型厂商吗？

能。设置 `AI_BASE_URL` 即可直连任意 OpenAI 兼容端点（如 DeepSeek、通义千问）；不设置时通过 Vercel AI Gateway 调用 `provider/model` 形式的模型。需要接入不兼容 OpenAI 协议的厂商时，在 `server/plugins/` 中用 `modelProviderRegistry.register()` 注册对应的 AI SDK provider。见 [AI Chat](https://docs.mhaibaraai.cn/docs/ai/ai-chat)。

## 不想启用 AI Chat 怎么办？

不配置 `AI_API_KEY` 即可，AI Chat 默认不启用，相关依赖也不会打包。构建环境中存在 `AI_API_KEY` 但不需要 AI Chat 时，设置 `aiChat.enabled: false`。见[功能开关](https://docs.mhaibaraai.cn/docs/guide/features)。

## 如何升级 Layer？

升级 `@movk/nuxt-docs` 的版本后重新安装依赖：

```bash [pnpm]
pnpm add @movk/nuxt-docs@latest
```

```bash [npm]
npm install @movk/nuxt-docs@latest
```

```bash [yarn]
yarn add @movk/nuxt-docs@latest
```

```bash [bun]
bun add @movk/nuxt-docs@latest
```

从 v2 升级到 v3 时，先阅读[迁移指南](https://docs.mhaibaraai.cn/docs/getting-started/migration)，其中列出了全部破坏性变更。每个版本的改动见[版本发布](https://docs.mhaibaraai.cn/releases)。

## 如何修改页头、页脚等界面组件？

在项目的 `app/components/` 中创建同名组件即可覆盖 Layer 的实现，例如 `app/components/HeaderLogo.vue`。只有[覆盖契约](https://docs.mhaibaraai.cn/docs/guide/customization)中列出的组件承诺在 v3.x 内保持名称、挂载位置与 props 稳定，未列出的组件属于内部实现。只想调整导航链接时，优先使用 `app.config` 的 `header.nav`，见[导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation)。

## 如何更换主色或字体？

默认主色为 `vermilion`（朱红），中性色为 `paper`（暖灰），标题使用衬线字体。主色通过 `app.config` 的 `ui.colors` 修改，标题字体通过 `theme.font` 切换为全站无衬线。见[主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme)。

## 可以部署成纯静态站点吗？

可以，运行 `nuxt generate` 后把 `.output/public/` 部署到任意静态托管。页面、搜索、组件文档与 OG 图片都正常工作，但 AI Chat、MCP Server、提交记录和 Markdown 内容协商依赖服务端，静态站点中不可用。见[部署](https://docs.mhaibaraai.cn/docs/guide/deployment#%E9%9D%99%E6%80%81%E7%94%9F%E6%88%90)。

## AI 代理如何读取我的文档？

Layer 默认提供 `llms.txt`、MCP Server 与 Markdown 内容协商：代理请求页面时可直接拿到 Markdown，`/raw/**.md` 提供每页的 Markdown 版本。见 [llms.txt](https://docs.mhaibaraai.cn/docs/ai/llms-txt)、[MCP Server](https://docs.mhaibaraai.cn/docs/ai/mcp) 与[代理发现](https://docs.mhaibaraai.cn/docs/ai/agent-discovery)。

## 构建很慢或内存不足怎么办？

关闭不需要的功能能明显减少构建开销，例如 `movkNuxtDocs.ogImage: false` 跳过每页的 OG 图片渲染。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
