静态资源

Astro 无需配置即支持大多数静态资源。你可以在项目的任何地方使用 import 语句(包括 Astro frontmatter 脚本),Astro 将在最终构建中内置优化后的静态资源副本。在 CSS 和 <style> 标签中也可以使用 @import

下面的文件类型 Astro 开箱即用:

  • Astro 组件 (.astro)
  • Markdown (.md)
  • JavaScript (.js, .mjs)
  • TypeScript (.ts, .tsx)
  • NPM 包
  • JSON (.json)
  • JSX (.jsx, .tsx)
  • CSS (.css)
  • CSS 模块 (.module.css)
  • 图片和资源 (.svg, .jpg, .png, etc.)

如果你没有看到要找的资源类型,请查看我们的集成库。你可以自行扩展 Astro 来支持不同文件类型,比如 Svelte 和 Vue 组件。

本指南详细介绍了如何在 Astro 中构建并成功导入不同类型的资源。

记住,你也可以把任何静态资产放在你的项目的 public/ 目录中,Astro 不加修改地直接复制到最终构建中。Astro构建或捆绑 public/ 中的文件,这意味支持所有类型的文件。你可以在 HTML 模板中通过 URL 路径直接引用 public/ 下的文件。

import { getUser } from './user.js';

可以使用普通的 ESM importexport 语法来导入 JavaScript。它在 Node.js 和浏览器中和预期保持一致。

import { getUser } from './user';
import type { UserType } from './user';

Astro 内置对 TypeScript 的支持。你可以在 Astro 项目中直接导入 .ts.tsx 文件,甚至可以直接在 Astro 组件脚本和任意 hoisted script 标签 中编写 TypeScript 代码。

Astro 本身不进行任何类型检查。类型检查应该在 Astro 之外进行或由 IDE 或通过一个单独的脚本来处理。Astro VSCode 扩展 会自动为打开的文件中提供 TypeScript 提示和错误警告。或使用 astro check 命令 检查 Astro 文件的类型。

📚 了解更多 Astro 中的 TypeScript

import { MyComponent } from './MyComponent.jsx';

Astro 内置对 JSX(*.jsx*.tsx)文件的支持。JSX 语法会自动转译为 JavaScript。

虽然 Astro 能理解 JSX 语法,但你需要使用框架集成来正确渲染 React、Preact 和 Solid 等框架。请查看我们的使用集成指南以了解更多。

// 返回 React & React-DOM npm 包
import React from 'react';
import ReactDOM from 'react-dom';

Astro 可以直接在浏览器中导入 npm 包。即使它是以传统格式发布的,Astro 也会在浏览器中运行前转译为 ESM。

// 使用默认导入加载 JSON 对象
import json from './data.json';

Astro 支持直接在应用程序中导入 JSON 文件。导入文件会通过默认导入返回完整的 JSON 对象。

// 加载并将 'style.css' 注入到页面上。
import './style.css';

Astro 支持直接在应用程序中导入 CSS 文件。导入的样式没有暴露出口,但导入样式会自动将这些样式添加到页面中。它默认支持所有 CSS 文件,并且可以通过插件支持 CSS 编译语言,如 Sass & Less。

如果你不喜欢写 CSS,Astro 也支持所有流行的 CSS-in-JS 库(如 styled-components)的样式。

// 1. 将 './style.module.css' 转换为类名唯一、有范围的值。
// 2. 返回对象,并将原始类名映射到其最终范围值的。
import styles from './style.module.css';

// This example uses JSX, but you can use CSS Modules with any framework.
return <div className={styles.error}>Your Error Message</div>;

Astro 支持使用 [name].module.css 命名约定的 CSS 模块。像导入任何 CSS 文件一样,导入 CSS 会应用到页面。然而,CSS 模块默认导出特殊的 styles 对象,并将你的原始类名映射到唯一的标识符。

CSS 模块帮助你在前端强制执行组件样式隔离,并生成唯一的样式表类名。

import imgReference from './image.png'; // img === '/src/image.png'
import svgReference from './image.svg'; // svg === '/src/image.svg'
import txtReference from './words.txt'; // txt === '/src/words.txt'

// 这个例子使用 JSX,但你可以在任何框架下使用导入引用。
<img src={imgReference} />;

所有其他没有明确提到的资源可以通过 ESM 的 import 语句导入,并将返回最终构建中的资源引用连接。这对使用链接引用非 JS 资源很有用,比如创建一个带有 src 属性的图片元素指向该图片。

将图片放在 public/ 文件夹中也很有用,这在项目结构页面中有所解释。

// 加载并初始化所请求的 WASM 文件
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astro 支持使用浏览器的 WebAssembly API 直接在应用程序中 WASM 文件。

我们鼓励 Astro 用户尽可能避免使用 Node.js 内置模块(fspath 等.)。Astro 计划在未来与多个 JavaScript 运行时兼容。包括 DenoCloudflare Workers,它们不支持诸如 fs 等 Node 内置模块。

我们目标为常用的 Node.js 内置模块提供 Astro 化替代品。然而现在还没有这样的替代品。因此,如果真的需要,我们不会阻止你使用这些内置模块。Astro 支持使用较新 node: 前缀的 Node.js 内置模块。例如,如果你想读取一个文件,你可以这样做。

---
// 示例:从 Node.js 中导入内置模块 "fs/promises"
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const data = JSON.parse(json);
---

<span>Version: {data.version}</span>