静态资源

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 import 和 export 语法来导入 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 内置模块（fs、path 等.）。Astro 计划在未来与多个 JavaScript 运行时兼容。包括 Deno 和 Cloudflare 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>