跳转到内容
v5-beta

安装并设置 Astro

create astro CLI 命令 是从零开始创建一个新的 Astro 项目的最快方式。它将引导你完成设置新 Astro 项目的每一个步骤，并允许你从几个不同的官方起始模板中选择。

或者，你可以使用任何现有的主题或起始模板开始你的项目。

如果想要手动安装 Astro，请查看我们的逐步手动安装指南。

前提条件

段落标题 前提条件
  • Node.js - v18.17.1 或 v20.3.0 或更高版本。（不支持 v19。）
  • 文本编辑器 - 我们推荐使用 VS Code 并安装我们的 官方 Astro 扩展。
  • 终端 - Astro 通过其命令行界面（CLI）访问。

浏览器兼容性

段落标题 浏览器兼容性

Astro 使用 Vite 构建，Vite 默认针对支持现代 JavaScript 的浏览器。要阅读完整的参考，你可以 在 Vite 中查看当前支持的浏览器版本列表。

开始一个新项目

段落标题 开始一个新项目

通过 CLI 向导安装

段落标题 通过 CLI 向导安装

  1. 在你的终端运行以下命令以启动我们的便捷安装向导：

    终端窗口
    # 使用 npm 创建一个新项目
    npm create astro@latest

    你可以在你的机器上的任何地方运行 create astro，因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导将会自动为你创建一个。

    如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。现在你的项目已经创建好了，你可以 cd 进入你的新项目目录开始使用 Astro。

  2. 如果你在 CLI 向导中跳过了 “Install dependencies?”（安装依赖？） 步骤，那么在继续之前请确保安装你的依赖。

  3. 现在你可以 启动 Astro 开发服务器 并在构建时看到你的项目的实时预览！

使用主题或起始模板

段落标题 使用主题或起始模板

你也可以通过向 create astro 命令传递 --template 参数，基于 官方示例 或任何 GitHub 仓库的 main 分支开始一个新的 Astro 项目。

  1. 浏览我们的 主题和起始模板展示，在这里你可以浏览博客、作品集、文档站点、落地页等主题！或者在 GitHub 上搜索更多的起始项目。

  2. 在你的终端运行以下命令，替换官方 Astro 起始模板的名称，或你想使用的 GitHub 用户名和仓库：

    终端窗口
    # 使用官方示例创建一个新项目
    npm create astro@latest -- --template <example-name>
    

    # 基于 GitHub 仓库的 main 分支创建一个新项目
    npm create astro@latest -- --template <github-username>/<github-repo>

    默认情况下，此命令将使用模板仓库的 main 分支。如果要使用不同的分支名称，请在 --template 参数中指定：<github-username>/<github-repo>#<branch>。

  3. 回答 CLI 向导的问题并遵循其指示。

  4. 现在你可以 启动 Astro 开发服务器 并在自定义项目的同时查看实时预览！

编辑你的项目

段落标题 编辑你的项目

要对项目进行更改，请在代码编辑器中打开项目文件夹。在开发模式下运行开发服务器，能让你在编辑代码时查看站点的更新。

你还可以 自定义开发环境的各个方面 ，例如配置 TypeScript 或者安装官方 Astro 编辑器扩展。

启动 Astro 开发服务器

段落标题 启动 Astro 开发服务器

Astro 自带了一个内置的开发服务器，它包含了项目开发所需的一切。astro dev CLI 命令将启动本地开发服务器，让你第一次看到你的新网站。

每个起始模板都预配置了一个脚本，该脚本将为你运行 astro dev。在进入你的项目目录后，使用你喜欢的包管理器运行此命令并启动 Astro 开发服务器。

终端窗口
npm run dev

如果一切顺利，Astro 将在 http://localhost:4321/ 上为你的项目提供服务。在浏览器中访问该链接，查看你的新网站！

开发模式工作

段落标题 开发模式工作

Astro 将监听你的 src/ 目录中的实时文件更改，并在你构建时更新你的网站预览，因此在开发过程中你无需重启服务器。当开发服务器运行时，你总能在浏览器中看到你网站的最新版本。

在浏览器中查看你的网站时，你将能够访问 Astro 开发工具栏。在你构建时，它将帮助你检查你的 群岛，发现无障碍问题等。

如果在启动开发服务器后无法在浏览器中打开你的项目，请返回运行 dev 命令的终端并检查显示的消息。它应该会告诉你是否发生了错误，或者你的项目是否在不同的 URL http://localhost:4321/ 上提供服务。

配置你的开发环境

段落标题 配置你的开发环境
编辑器设置 自定义你的代码编辑器以改善 Astro 开发者体验并解锁新功能。
开发工具栏 探索开发工具栏中好用的功能。

Astro 中的 TypeScript

段落标题 Astro 中的 TypeScript

Astro 内置了对 TypeScript 的支持，它可以通过在你的代码中定义对象和组件的形状来帮助防止运行时错误。

你不需要在你的 Astro 项目中编写 TypeScript 代码也可以从中受益。Astro 总是将你的组件代码视为 TypeScript，并且 Astro VSCode 扩展 将尽可能推断以在你的编辑器中提供自动补全、提示和错误。

阅读更多关于在 Astro 中使用和配置 TypeScript 的内容

构建并预览你的网站

段落标题 构建并预览你的网站

若要检查将在构建时创建的网站版本，请退出开发服务器（Ctrl + C）并在你的终端中运行适用于你的包管理器的相应构建命令：

终端窗口
npm run build

Astro 将在一个单独的文件夹（默认为 dist/）中构建你的网站的可部署版本，并且你可以在终端中看到其进度。这将在你部署到生产环境之前提醒你项目中的任何构建错误。如果 TypeScript 配置为 strict 或 strictest，build 脚本还将检查你的项目中的类型错误。

当构建完成后，在你的终端中运行适当的 preview 命令（例如 npm run preview），你就可以在同一个浏览器预览窗口中本地查看你的网站的构建版本。

请注意，这将预览你在最后一次运行构建命令时的代码状态。这旨在让你预览你的网站在 部署到网络 时的样子。在构建后对代码进行的任何更改都不会在你预览网站时反映出来，直到你再次运行构建命令。

使用（Ctrl + C）退出预览并在终端中运行另一个命令，例如重新启动开发服务器以返回 开发模式工作，它会随着你的编辑更新以显示你的代码更改的实时预览。

阅读更多关于 Astro CLI 和你在使用 Astro 构建时将使用的终端命令。

部署你的新网站

段落标题 部署你的新网站

你可能希望 立即部署你的新网站，在你开始添加或更改太多代码之前。这有助于发布你的网站的最小工作版本，并可以节省你以后排查部署问题的时间和精力。

接下来

段落标题 接下来

好了！你现在可以开始使用 Astro 构建了！🥳

以下是我们建议接下来探索的几个主题，你可以按任何顺序阅读它们。你甚至可以暂时离开我们的文档去玩转你的新 Astro 项目代码库，当你遇到麻烦或有疑问时，欢迎你随时返回这里。

探索 Astro 的特性

段落标题 探索 Astro 的特性
了解你的代码库 在我们的项目结构指南中了解 Astro 的文件结构。
创建内容集合 通过 frontmatter 验证和自动类型安全向你的新网站添加内容。
添加视图过渡 创建无缝页面过渡和动画。
了解群岛 阅读关于 Astro 的群岛结构。

学习入门教程

段落标题 学习入门教程

在我们的入门教程中，从一个空白页面开始构建一个完全功能的 Astro 博客。

这是一个了解 Astro 工作原理的好方法，它会引导你了解页面、布局、组件、路由、群岛等基础知识。对于那些对 Web 开发概念比较陌生的人，它还包括一个可选的、适合初学者的单元，将指导你在你的计算机上安装必要的应用程序、创建一个 GitHub 账户，并部署你的网站。

手动设置

段落标题 手动设置

本指南将指导你手动安装和配置新的 Astro 项目。

如果你不想使用我们的自动 create astro CLI 工具，可以按照下面的指南自行设置你的项目。

  1. 创建你的目录

    创建一个以你的项目命名的空目录，然后进入该目录。

    终端窗口
    mkdir my-astro-project
    cd my-astro-project

    进入你的新目录后，创建你的项目 package.json 文件。这是你管理项目依赖项（包括 Astro）的方式。如果你不熟悉这种文件格式，请运行以下命令创建一个。

    终端窗口
    npm init --yes

  2. 安装 Astro

    首先，在你的项目中安装 Astro 的依赖项。

    终端窗口
    npm install astro

    然后，用以下内容替换你的 package.json 中的任何占位符 “scripts” 部分：

    package.json
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "start": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },

    你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。

  3. 创建你的第一个页面

    在你的文本编辑器中，在你的目录下的 src/pages/index.astro 创建一个新文件。这将是你项目中的第一个 Astro 页面。

    对于本指南，请将以下代码片段（包括 --- 破折号）复制并粘贴到你的新文件中：

    src/pages/index.astro
    ---
    // 欢迎使用 Astro！这些三破折号代码围栏之间的内容是你的 "component frontmatter"。它不会在浏览器中运行。
    console.log('这段代码在你的终端运行，而不是在浏览器中！');
    ---
    <!-- 下面是你的 "component template"。它只是 HTML，但加入了一些魔法，帮助你构建出色的模板。 -->
    <html>
      <body>
        <h1>Hello, World!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>

  4. 创建你的第一个静态资源

    你还需要创建一个 public/ 目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源，因此你可以安全地从你的组件模板中引用它们。

    在你的文本编辑器中，在你的目录下的 public/robots.txt 创建一个新文件。robots.txt 是大多数网站会包含的一个简单文件，用于告诉像 Google 这样的搜索机器人如何处理你的网站。

    对于本指南，请将以下代码片段复制并粘贴到你的新文件中：

    public/robots.txt
    # 示例：允许所有机器人扫描并索引你的网站。
    # 完整语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /

  5. 创建 astro.config.mjs

    Astro 使用 astro.config.mjs 进行配置。如果你不需要配置 Astro，这个文件是可选的，但你现在可能希望创建它。

    在你项目的根目录下创建 astro.config.mjs，并将下面的代码复制到其中：

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    

    // https://astro.build/config
    export default defineConfig({});

    如果你想在你的项目中包含 UI 框架组件，如 React、Svelte 等，或使用其他工具，如 Tailwind 或 Partytown，这里是你手动导入和配置集成的地方。

    阅读 Astro 的 API 配置参考 以获取更多信息。

  6. 添加 TypeScript 支持

    TypeScript 使用 tsconfig.json 进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，以便工具（如 Astro 和 VS Code）了解你的项目。某些功能（如 npm 包导入）在没有 tsconfig.json 文件的情况下在编辑器中不完全支持。

    如果你打算编写 TypeScript 代码，建议使用 Astro 的 strict 或 strictest 模板。你可以在 astro/tsconfigs/ 查看并比较三种模板配置。

    在你项目的根目录下创建 tsconfig.json，并将下面的代码复制到其中。（你可以使用 base、strict 或 strictest 作为你的 TypeScript 模板）：

    tsconfig.json
    {
      "extends": "astro/tsconfigs/base"
    }

    阅读 Astro 的 TypeScript 设置指南 以获取更多信息。

  7. 接下来

    如果你已经按照上面的步骤操作，你的项目目录现在应该如下所示：

    • 文件夹node_modules/
      • …
    • 文件夹public/
      • robots.txt
    • 文件夹src/
      • 文件夹pages/
        • index.astro
    • astro.config.mjs
    • package-lock.json 或 yarn.lock、pnpm-lock.yaml 等。
    • package.json
    • tsconfig.json

  8. 现在你可以启动 Astro 开发服务器 并在构建项目的同时查看实时预览了！

贡献

你有什么想法？

创建 GitHub Issue

向我们的团队发出问题警报的最快方法。

社区