手动安装 Astro

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

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

先决条件

¥Prerequisites

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

安装

¥Installation

如果你不想使用我们的自动 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.

1. 创建你的目录

¥ 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

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

¥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 init --yes

pnpm init

yarn init --yes

2. 安装 Astro

¥ Install Astro

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

¥First, install the Astro project dependencies inside your project.

npm install astro

pnpm add astro

yarn add astro

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

¥Then, replace any placeholder “scripts” section of your package.json with the following:

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

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

¥You’ll use these scripts later in the guide to start Astro and run its different commands.

3. 创建你的第一个页面

¥ Create your first page

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

¥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>

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

¥ Create your first static asset

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

¥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.

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

¥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:

# 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: /

5. 创建 `astro.config.mjs`

¥ Create astro.config.mjs

Astro 使用 astro.config.mjs 配置。如果你不需要配置 Astro，则此文件是可选的，但你可能希望立即创建它。

¥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.

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

¥Create astro.config.mjs at the root of your project, and copy the code below into it:

import { defineConfig } from 'astro/config';

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

如果你想包含 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。

¥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.

6. 添加 TypeScript 支持

¥ Add TypeScript support

TypeScript 使用 tsconfig.json 配置。即使你不编写 TypeScript 代码，该文件也很重要，以便 Astro 和 VS Code 等工具知道如何理解你的项目。如果没有 tsconfig.json 文件，编辑器将无法完全支持某些功能（例如 npm 包导入）。

¥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.

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

¥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/.

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

¥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):

{
  "extends": "astro/tsconfigs/base"
}

最后，创建 src/env.d.ts 让 TypeScript 了解 Astro 项目中可用的环境类型：

¥Finally, create src/env.d.ts to let TypeScript know about ambient types available in an Astro project:

/// <reference types="astro/client" />

Read Astro’s TypeScript setup guide for more information.

7. 下一步

¥ 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
- env.d.ts
astro.config.mjs
package-lock.json or yarn.lock, pnpm-lock.yaml, etc.
package.json
tsconfig.json

恭喜，你现在已经可以使用 Astro 了！

¥Congratulations, you’re now set up to use Astro!

如果你完全遵循本指南，你可以直接跳至步骤 2:启动 Astro 继续并学习如何首次运行 Astro。

¥If you followed this guide completely, you can jump directly to Step 2: Start Astro to continue and learn how to run Astro for the first time.