跳转到内容
Astro v5 来临！了解如何升级你的网站

安装 Astro

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

你还可以运行带有 template 标志的 CLI 命令，以使用任何现有主题或起始模板来开始你的项目。探索我们的 主题和起始模板 showcase，你可以在其中浏览到博客、作品集、文档网站、落地页等主题！

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

前提条件

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

浏览器兼容性

段落标题 浏览器兼容性

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

通过 CLI 向导安装

段落标题 通过 CLI 向导安装

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

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

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

    如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。

  2. 现在你的项目已经创建好了，你可以 cd 进入你的新项目目录开始使用 Astro。

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

    终端窗口
    npm install

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

CLI 安装标志

段落标题 CLI 安装标志

你可以运行带有附加标志的 create astro 命令来自定义安装的过程（例如，对每次询问都统一回答“是”，跳过 Houston 动画）或你的新项目（例如，是否安装 git，添加集成）。

请参阅所有可用的 create astro 命令标志

添加集成

段落标题 添加集成

你可以通过向 create astro 命令传递 --add 参数，它会在开始一个新的 astro 项目的同时，为其安装任何支持 astro add 命令的 官方集成 或社区集成。

在你的终端中运行以下命令，可以替换为任何支持 astro add 命令的集成：

终端窗口
# 创建一个带有 react 和 tailwind 的新项目
npm create astro@latest -- --add react --add tailwind

使用主题或起始模板

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

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

在你的终端中运行以下命令，可以替换为官方 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>。

手动设置

段落标题 手动设置

本指南将指导你手动安装和配置新的 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",
        "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 开发服务器 并在构建项目的同时查看实时预览了！

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community