安装 Astro

create astro CLI 命令是从头开始启动新 Astro 项目的最快方法。它将引导你完成设置新 Astro 项目的每个步骤，并允许你从几个不同的官方入门模板中进行选择。

¥The create astro CLI command is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates.

你还可以使用 template 标志运行 CLI 命令，以使用任何现有主题或入门模板开始你的项目。探索我们的主题和入门展示，你可以在其中浏览博客、作品集、文档站点、登录页面等主题！

¥You can also run the CLI command with the template flag to begin your project using any existing theme or starter template. Explore our themes and starters showcase where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more!

要手动安装 Astro，请参阅我们的分步手动安装指南。

¥To install Astro manually instead, see our step-by-step manual installation guide.

先决条件

¥Prerequisites

Node.js - v18.17.1 或 v20.3.0、v22.0.0 或更高版本。（不支持 v19 和 v21。）
文本编辑器 - 我们建议将 VS Code 与我们的官方 Astro 扩展一起使用。
终端 - Astro 可通过其命令行接口 (CLI) 访问。

浏览器兼容性

¥Browser compatibility

Astro 是使用 Vite 构建的，默认情况下针对具有现代 JavaScript 支持的浏览器。有关完整参考，请参阅 Vite 中当前支持的浏览器版本列表。

¥Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the list of currently supported browser versions in Vite.

从 CLI 向导安装

¥Install from the CLI wizard

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

¥You can run create astro anywhere on your machine, so there’s no need to create a new empty directory for your project before you begin. If you don’t have an empty directory yet for your new project, the wizard will help create one for you automatically.

Run the following command in your terminal to start the install wizard:
- npm
- pnpm
- Yarn
终端窗口
# create a new project with npm npm create astro@latest
终端窗口
# create a new project with pnpm pnpm create astro@latest
终端窗口
# create a new project with yarn yarn create astro
If all goes well, you will see a success message followed by some recommended next steps.
Now that your project has been created, you can cd into your new project directory to begin using Astro.
If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing.
- npm
- pnpm
- Yarn
终端窗口
npm install
终端窗口
pnpm install
终端窗口
yarn install
You can now start the Astro dev server and see a live preview of your project while you build!

CLI 安装标志

¥CLI installation flags

你可以使用其他标志运行 create astro 命令来自定义设置过程（例如，回答 “yes” 的所有问题、跳过休斯顿动画）或新项目（例如，是否安装 git、添加集成）。

¥You can run the create astro command with additional flags to customize the setup process (e.g. answering “yes” to all questions, skipping the Houston animation) or your new project (e.g. install git or not, add integrations).

See all the available create astro command flags

添加集成

¥Add integrations

你可以通过将 --add 参数传递给 create astro 命令来启动一个新的 astro 项目并同时安装支持 astro add 命令的任何官方集成或社区集成。

¥You can start a new astro project and install any official integrations or community integrations that support the astro add command at the same time by passing the --add argument to the create astro command.

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

¥Run the following command in your terminal, substituting any integration that supports the astro add command:

# create a new project with react and tailwind
npm create astro@latest -- --add react --add tailwind

# create a new project with react and tailwind
pnpm create astro@latest --add react --add tailwind

# create a new project with react and tailwind
yarn create astro --add react --add tailwind

使用主题或入门模板

¥Use a theme or starter template

你可以通过将 --template 参数传递给 create astro 命令来基于官方示例或任何 GitHub 存储库的 main 分支启动一个新的 astro 项目。

¥You can start a new astro project based on an official example or the main branch of any GitHub repository by passing a --template argument to the create astro command.

在你的终端中运行以下命令，替换官方 Astro 入门模板名称或你要使用的主题的 GitHub 用户名和存储库：

¥Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use:

# create a new project with an official example
npm create astro@latest -- --template <example-name>

# create a new project based on a GitHub repository’s main branch
npm create astro@latest -- --template <github-username>/<github-repo>

# create a new project with an official example
pnpm create astro@latest --template <example-name>

# create a new project based on a GitHub repository’s main branch
pnpm create astro@latest --template <github-username>/<github-repo>

# create a new project with an official example
yarn create astro --template <example-name>

# create a new project based on a GitHub repository’s main branch
yarn create astro --template <github-username>/<github-repo>

默认情况下，此命令将使用模板存储库的 main 分支。要使用不同的分支名称，请将其作为 --template 参数的一部分传递：<github-username>/<github-repo>#<branch>。

¥By default, this command will use the template repository’s main branch. To use a different branch name, pass it as part of the --template argument: <github-username>/<github-repo>#<branch>.

手动设置

¥Manual Setup

本指南将引导你完成手动安装和配置新 Astro 项目的步骤。

¥This guide will walk you through the steps to manually install and configure a new Astro project.

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

¥If you prefer not to use our automatic create astro CLI tool, you can set up your project yourself by following the guide below.

Create your directory

Create an empty directory with the name of your project, and then navigate into it.
终端窗口
```
mkdir my-astro-project
cd my-astro-project
```
Once you are in your new directory, create your project package.json file. This is how you will manage your project dependencies, including Astro. If you aren’t familiar with this file format, run the following command to create one.
- npm
- pnpm
- Yarn
终端窗口
npm init --yes
终端窗口
pnpm init
终端窗口
yarn init --yes
Install Astro

First, install the Astro project dependencies inside your project.

Astro must be installed locally, not globally. Make sure you are not running npm install -g astro pnpm add -g astro or yarn add global astro.
- npm
- pnpm
- Yarn
终端窗口
npm install astro
终端窗口
pnpm add astro
终端窗口
yarn add astro
Then, replace any placeholder “scripts” section of your package.json with the following:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
You’ll use these scripts later in the guide to start Astro and run its different commands.

Create your first page

In your text editor, create a new file in your directory at src/pages/index.astro. This will be your first Astro page in the project.

For this guide, copy and paste the following code snippet (including --- dashes) into your new file:

---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
    some magic sprinkled in to help you build great templates. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

Create your first static asset

You will also want to create a public/ directory to store your static assets. Astro will always include these assets in your final build, so you can safely reference them from inside your component templates.

In your text editor, create a new file in your directory at public/robots.txt. robots.txt is a simple file that most sites will include to tell search bots like Google how to treat your site.

For this guide, copy and paste the following code snippet into your new file:
public/robots.txt
```
# Example: Allow all bots to scan and index your site.
# Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
Create astro.config.mjs

Astro is configured using astro.config.mjs. This file is optional if you do not need to configure Astro, but you may wish to create it now.

Create astro.config.mjs at the root of your project, and copy the code below into it:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
If you want to include UI framework components such as React, Svelte, etc. or use other tools such as Tailwind or Partytown in your project, here is where you will manually import and configure integrations.

Read Astro’s API configuration reference for more information.
Add TypeScript support

TypeScript is configured using tsconfig.json. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.

If you do intend to write TypeScript code, using Astro’s strict or strictest template is recommended. You can view and compare the three template configurations at astro/tsconfigs/.

Create tsconfig.json at the root of your project, and copy the code below into it. (You can use base, strict, or strictest for your TypeScript template):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Read Astro’s TypeScript setup guide for more information.
Next Steps

If you have followed the steps above, your project directory should now look like this:
- Directorynode_modules/
  - …
- Directorypublic/
  - robots.txt
- Directorysrc/
  - Directorypages/
    index.astro
- astro.config.mjs
- package-lock.json or yarn.lock, pnpm-lock.yaml, etc.
- package.json
- tsconfig.json
You can now start the Astro dev server and see a live preview of your project while you build!