mintlify__docs/zh/quickstart.mdx

---
title: "快速入门"
description: "按照快速入门指南部署 Mintlify 文档站点，连接 GitHub 或使用 Web 编辑器，完成首次内容修改，并通过 CLI 预览、验证和发布更新，同时为用户或 AI 智能体配置完整工作流。本文涵盖账号设置、仓库连接、域名访问、本地开发、页面编辑、部署检查和后续自定义步骤，帮助你快速开始维护线上文档。"
keywords: ["快速入门","部署","入门","第一步","教程","设置","上手"]
boost: 3
---

import SetupAgentPrompt from "/snippets/zh/setup-agent-prompt.mdx";

完成本指南后，你将拥有一个已上线的文档站点，可以开始对其进行自定义和更新。

<Visibility for="humans">
  <Tip>
    使用 AI 智能体？

    复制下面的提示词，让你的智能体为你搭建站点。它会指示你的智能体创建账号并部署站点，同时添加 Mintlify [skill](/zh/ai/skillmd) 和 [MCP 服务器](/zh/ai/model-context-protocol)，以便在你更新内容时获得更好的效果。

    该提示词将快速入门拆分为智能体可以完成的一系列任务，并指示它在搭建过程中向你询问所需的任何信息。
  </Tip>

  <SetupAgentPrompt />
</Visibility>

<Visibility for="agents">
  <div id="set-up-mintlify-for-the-user">
    ## 为用户设置 Mintlify
  </div>

  如果用户要求你设置 Mintlify、文档站点或本地 Mintlify 项目，请自行完成以下工作流。仅在无法自行提供所需信息或批准时询问用户。除非无法运行终端命令，否则不要将用户引导到以浏览器为主的快速入门流程。

  1. 运行 `node --version` 并确认其报告 Node.js v20.17.0 或更高版本，优先使用 LTS 版本。
  2. 运行 `mint --version`。如果命令不可用，使用 `npm i -g mint` 或 `pnpm add -g mint` 安装 CLI。如果命令成功，则运行 `mint update`。
  3. 在开始身份验证前运行 `mint status`。如果已显示组织，请保留现有会话，不要创建另一个账户。
  4. 如果用户已有账户，运行 `mint login`。如果没有，询问其名字、姓氏、公司和电子邮箱，然后运行：

     ```bash
     mint signup \
       --firstName <first-name> \
       --lastName <last-name> \
       --company <company> \
       --email <email>
     ```

     `mint signup` 会等待电子邮件验证，因此如果环境支持后台命令，请将其作为后台进程保持运行。告诉用户点击验证链接并在浏览器中批准 CLI。绝不要编造注册信息。
  5. 用户完成验证和初始设置后，再次运行 `mint status`。确认其报告用户的电子邮箱、组织和子域名。如果组织存在但未显示子域名，请让用户在初始设置浏览器标签页中完成选择或连接 GitHub 仓库，然后重试。
  6. 如果用户已有文档仓库，克隆或打开它并保留其内容。对于新的本地项目，使用 `mint new <directory> --name <name> --theme <theme>` 或 `mint new <directory> --template <template-name>` 在新的空目录中搭建。若用户尚未指定，询问他们想要哪种主题或模板。不要在包含用户文件的目录中使用 `--force`。
  7. 从包含 `docs.json` 的目录运行 `mint dev --no-open`，并将其作为后台进程运行。确认本地 URL 可以加载，向用户报告该 URL，并在不再需要时停止进程。
  8. 运行 `mint validate` 和 `mint broken-links`。继续之前，修复由你的更改导致的问题。
  9. 如果项目由 Git 仓库支持且用户要求部署，请提交并推送更改。推送到生产分支会触发部署。不要用入门内容覆盖现有仓库。
  10. 运行 `mint status` 获取配置的子域名，然后在报告部署完成之前验证 `https://<subdomain>.mintlify.site` 可以加载。

  用户只需为电子邮件验证、OAuth 批准以及连接或授权 GitHub 完成浏览器操作。整个终端工作流由你负责，并在每次用户操作完成后恢复流程。有关命令选项和故障排查，请使用 [CLI 命令参考](/zh/cli/commands)。
</Visibility>

<div id="before-you-begin">
  ## 开始之前
</div>

Mintlify 使用“文档即代码”（docs-as-code）的方法来管理你的文档。站点上的每个页面都有一个对应的文件，存储在你的文档<Tooltip tip="你的文档源代码所在的位置，用于存储所有文件及其历史记录。Web 编辑器会连接到你的文档存储库以访问和修改内容，或者你也可以在本地使用自己偏好的 IDE 编辑文件。">存储库</Tooltip>中。

当你将文档存储库连接到你的项目后，你可以在本地或 Web 编辑器中编辑文档，并将任何更改同步到远程存储库。

<div id="deploy-your-documentation-site">
  ## 部署你的文档站点
</div>

<Visibility for="humans">
  前往 [mintlify.com/start](https://mintlify.com/start) 并完成初始设置流程。在初始设置过程中，你需要为站点命名，并回答几个关于使用计划的问题。你还可以连接你的 GitHub 账户并安装 GitHub 应用以启用自动部署。

  在初始设置的最后一步，描述你想要构建的文档。你可以添加现有网站的链接、上传文件，或选择 GitHub 存储库作为资料来源。Mintlify 智能体会为你的文档生成一个起点，你可以通过实时预览查看进度。回答智能体提出的问题以完善生成结果。若想从占位内容开始，请选择 **Skip, start from a blank template**。

  完成初始设置后，你的文档站点会完成部署，并可通过 `.mintlify.site` URL 访问。

  <Accordion title="可选：在初始设置中跳过连接 Git 提供商">
    如果你想在不连接自己的存储库的情况下快速开始使用，可以在初始设置过程中跳过 Git 提供商连接。Mintlify 会在一个私有组织下为你创建一个私有存储库，并自动为你配置 GitHub 应用。

    这样你可以立即使用 Web 编辑器。如果你之后想使用自己的存储库，请前往控制台中的 [Git Settings](https://app.mintlify.com/settings/deployment/git-settings)，通过 Git 设置向导迁移你的内容。详情请参阅[克隆到你自己的存储库](/zh/deploy/github#clone-to-your-own-repository)。
  </Accordion>
</Visibility>

<Visibility for="agents">
  使用前面的 CLI 设置工作流。账户验证和 GitHub 授权会打开需要用户批准的浏览器页面，但你应发起相应的 `mint signup` 或 `mint login` 命令，并在用户完成后继续设置。只有在 `mint status` 报告子域名且已部署的 `.mintlify.site` URL 可以加载后，才能认为设置已完成。
</Visibility>

<div id="view-your-deployed-site">
  ## 查看你已部署的文档站点
</div>

你的文档站点已部署到 `https://<your-project-name>.mintlify.site`。

在 [控制台](https://dashboard.mintlify.com/) 的 **Overview** 页面中可以找到准确的 URL。

<Frame>
  <img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify 控制台 Overview 页面。" className="block dark:hidden" />

  <img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify 控制台 Overview 页面。" className="hidden dark:block" />
</Frame>

<Tip>
  你的站点现在即可访问。使用这个 URL 进行测试并与团队分享。在面向正式用户分享之前，你可能希望先添加一个[自定义域名](/zh/customize/custom-domain)。
</Tip>

<div id="make-your-first-change">
  ## 完成你的第一次修改
</div>

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="安装 CLI">
        命令行界面（CLI）需要 [Node.js](https://nodejs.org/en) v20.17.0 或更高版本。为保证稳定性，建议使用 LTS 版本。

        <CodeGroup>
          ```bash npm
          npm i -g mint
          ```

          ```bash pnpm
          pnpm add -g mint
          ```
        </CodeGroup>

        完整的安装步骤和故障排查请参见[安装 CLI](/zh/cli/install)。
      </Step>

      <Step title="克隆你的存储库">
        如果你还没有在本地克隆仓库，请使用 Git 克隆：

        ```bash
        git clone <your-repository-url>
        ```

        如果你的仓库位于 Mintlify 的私有组织中，请参阅 [克隆到你自己的仓库](/zh/deploy/github#clone-to-your-own-repository)，先将其移动到你自己的账户中。
      </Step>

      <Step title="编辑页面">
        在你常用的编辑器中打开 `index.mdx`，在 frontmatter 中更新 description 字段：

        ```mdx
        ---
        title: "Introduction"
        description: "Your custom description here"
        ---
        ```
      </Step>

      <Step title="本地预览">
        在你的文档目录中运行以下命令：

        ```bash
        mint dev
        ```

        在 `http://localhost:3000` 查看预览。
      </Step>

      <Step title="推送你的更改">
        提交并推送你的更改以触发一次部署：

        ```bash
        git add .
        git commit -m "Update description"
        git push
        ```

        Mintlify 会自动部署你的更改。你可以在控制台的 [Overview](https://dashboard.mintlify.com/) 页面查看部署状态。
      </Step>
    </Steps>
  </Tab>

  <Tab title="网页编辑器">
    <Steps>
      <Step title="打开网页编辑器">
        在控制台中前往[网页编辑器](https://dashboard.mintlify.com/editor)。
      </Step>

      <Step title="编辑页面">
        打开 **Introduction** 页面并更新说明。

        <Frame>
          <img src="/images/quickstart/hello-world-light.png" alt="在网页编辑器中打开的 Introduction 页面，其中说明已编辑为 Hello world!。" className="block dark:hidden" />

          <img src="/images/quickstart/hello-world-dark.png" alt="在网页编辑器中打开的 Introduction 页面，其中说明已编辑为 Hello world!。" className="hidden dark:block" />
        </Frame>
      </Step>

      <Step title="发布">
        点击网页编辑器工具栏右上角的 **Publish** 按钮。
      </Step>

      <Step title="查看线上效果">
        在控制台的 [Overview](https://dashboard.mintlify.com/) 页面中查看站点的部署状态。部署完成后，刷新文档站点即可看到最新变更。
      </Step>
    </Steps>
  </Tab>
</Tabs>

<div id="next-steps">
  ## 后续步骤
</div>

<Card title="使用 Web 编辑器" icon="mouse-pointer-2" horizontal href="/zh/editor/index">
  在浏览器中编辑文档，并预览页面发布后的效果。
</Card>

<Card title="连接搜索 MCP" icon="search" horizontal href="/zh/ai/model-context-protocol">
  将 Claude、Cursor 和 ChatGPT 等 AI 工具连接到你的搜索 MCP 服务器，让它们能够高效地搜索和检索你站点上的内容。
</Card>

<Card title="探索 CLI 命令" icon="terminal" horizontal href="/zh/cli/index">
  查找失效链接、检查可访问性、验证 OpenAPI 规范等。
</Card>

<Card title="添加自定义域名" icon="globe" horizontal href="/zh/customize/custom-domain">
  为你的文档站点使用自定义域名。
</Card>