配置参考
下面的参考资料涵盖了 Astro 所有支持的配置选项。要了解更多关于配置 Astro 的信息,请阅读我们的配置 Astro 指南。
类型:string
CLI: --root
默认:"."
(current working directory)
只有当你在项目根目录以外的目录下运行 astro
CLI 命令时,你才应该提供该选项。通常,这个选项是通过 CLI 而不是 Astro 配置文件提供的,因为 Astro 需要知道项目根目录才能找到配置文件。
如果提供相对路径(例如:--root: './my-project'
),Astro 会根据你当前的工作目录进行解析。
srcDir
Section titled srcDir类型:string
默认:"./src"
设置 Astro 将读取网站的目录。
这个值可以是绝对路径,也可以是相对路径。
publicDir
Section titled publicDir类型:string
默认:"./public"
设置静态资源目录。这个目录下的文件在开发过程中被提供给 /
,在构建过程中被复制到构建目录。这些文件总是按原样提供或复制的,没有转换或捆绑。
这个值可以是绝对路径,也可以是相对路径。
outDir
Section titled outDir类型:string
默认:"./dist"
设置 astro build
将你的最终构建写入的目录。
这个值可以是绝对路径,也可以是相对路径。
类型:string
你最终部署的链接。Astro 会使用这个完整的链接来生成网站地图和最终构建的规范链接。强烈建议你设置这个配置项,以获得 Astro 最佳体验。
类型:string
你要部署到的基本路径。Astro 在开发过程中会匹配这个路径名,这样你的开发环境就会尽可能地与你的构建环境匹配。在下面的例子中,astro dev
会在 /docs
处启动你的服务器。
请注意,使用 base
选项后你须要更改所有的链接。在这个例子中,你须要在链接前面添加 /docs/
前缀。
比如,当你想要使用某张图片时,你须要将 '/someimg.png'
改为 '/docs/someimg.png'
。
trailingSlash
Section titled trailingSlash类型:'always' | 'never' | 'ignore'
默认:'ignore'
设置设计服务器的路由匹配行为。从以下选项中选择:
'always'
- 只匹配包含尾部斜线的链接(例如:/foo/
)。'never'
- 不匹配包含尾部斜线的链接(例如:/foo
)。'ignore'
- 匹配链接,不管是否存在尾部的/
。
如果你的生产主机对尾部斜杠的工作或不工作有严格的处理方式,请使用该配置选项。
如果你希望自己更严格一些,那么你也可以设置这个选项,这样在开发过程中,无论是否有尾部斜杠的URL都不会工作。
另见:
- build.format
adapter
Section titled adapter类型:AstroIntegration
使用构建适配器将其部署到你最喜爱的服务器、无服务器或边缘主机。导入我们的第一方适配器 Netlify (EN)、Vercel,以及更多的适配器来使用Astro SSR。
有关 SSR 的更多信息,请参见我们的服务器端渲染指南,以及我们的部署指南以获得完整的主机列表。
另见:
- output
output
Section titled output类型:'static' | 'server'
默认值:'static'
指定构建的输出目标。
static
- 构建静态网站,部署到任何静态主机上。server
- 构建应用,部署到支持S SR(服务器端渲染)的主机上。
另见:
- adapter
build.format
Section titled build.format类型:('file' | 'directory')
默认:'directory'
控制每个页面的输出文件格式:
- 如果是’file’,Astro将为每个页面生成一个HTML文件(例如:“/foo.html”)。
- 如果是’directory’,Astro将为每个页面生成一个有嵌套的
index.html
文件的目录(例如:“/foo/index.html”)。
对 Astro.url 的影响
Section titled 对 Astro.url 的影响设置 build.format
可以控制 Astro.url
在构建过程中被设置成什么。当它是:
directory
-Astro.url.pathname
将包括一个尾部斜杠,以模仿文件夹行为;例如/foo/
。file
-Astro.url.pathname
将包括.html
,即/foo.html
。
这意味着当你使用 new URL('./relative', Astro.url)
创建相对的连接时,开发和构建会得到一致的行为。
服务器选项
Section titled 服务器选项定制 Astro 开发服务器,适用于 astro dev
和 astro preview
。
要根据运行的命令(dev
、preview
)设置不同的配置,也可以向这个配置选项传递函数。
server.host
Section titled server.host类型:string | boolean
默认:false
设置服务器应该监听哪些网络 IP 地址(即非本地主机 IP)。
false
- 不在网络 IP 地址上公开true
- 侦听所有地址,包括 LAN 和公开地址[custom-address]
- 在[custom-address]
网络 IP 地址上公开(例如:192.168.0.1
)。
server.port
Section titled server.port类型:number
默认:3000
设置服务器监听端口。
如果给定的端口已经在使用,Astro 会自动尝试下一个可用的端口。
Markdown 选项
Section titled Markdown 选项markdown.drafts
Section titled markdown.drafts类型:boolean
默认:false
控制 markdown 草稿页是否应该被包含在构建中。
如果 markdown 页面在 frontmatter 中包含 draft: true
,那么它就被认为是草稿。在开发过程中会显示草稿页(astro dev
),但在默认情况下,它们不会被包含在你的最终构建中。
markdown.shikiConfig
Section titled markdown.shikiConfig类型:Partial<ShikiConfig>
Shiki 配置选项。使用方法见 markdown 配置文档。
markdown.syntaxHighlight
Section titled markdown.syntaxHighlight类型:'shiki' | 'prism' | false
默认:shiki
可供使用的语法高亮器:
markdown.remarkPlugins
Section titled markdown.remarkPlugins类型:RemarkPlugins
通过自定义 Remark 插件来定制 Markdown 构建方式。你可以导入并应用插件函数(推荐),或传递一个值为插件名的字符串。
markdown.rehypePlugins
Section titled markdown.rehypePlugins类型:RehypePlugins
通过自定义 Rehype 插件 插件来定制对你的 Markdown 输出内容的处理方式。你可以导入并应用插件函数(推荐),或传递一个值为插件名的字符串。
markdown.extendDefaultPlugins
Section titled markdown.extendDefaultPlugins类型:boolean
默认值:false
Astro 默认应用 GitHub-flavored Markdown 和 Smartypants 插件。当添加你自己的 remark 或 rehype 插件时,你可以通过将 extendDefaultPlugins
标志为 true
来保留这些默认值。
markdown.remarkRehype
Section titled markdown.remarkRehype类型:RemarkRehype
向 remark-rehype 传递选项。
用自定义集成来扩展 Astro 功能。你可以用集成来添加框架支持(如 Solid.js)、新功能(如站点地图)和新库支持(如 Partytown 和 Turbolinks)。
请阅读我们的集成指南,以帮助开始使用Astro集成。
传递额外的配置选项给 Vite。适用于需要使用一些 Astro 不支持的高级配置。
在 vitejs.dev 上查看完整的 vite
配置对象文档。
Legacy 标志
Section titled Legacy 标志为了帮助一些用户在 Astro 不同版本之间进行迁移,我们偶尔会引入 legacy
标志。
这些标志允许你在最新的版本中选择使用 Astro 的一些废弃的或其他过时的行为,
这样你就可以继续升级并使用新的 Astro 版本。
legacy.astroFlavoredMarkdown
Section titled legacy.astroFlavoredMarkdown类型:boolean
默认值:false
启用 Astro pre-v1.0 对 .md
Markdown 文件中的组件和 JSX 表达式的支持。
在 Astro 1.0.0-rc
中,默认移除了这种原始的行为,以支持我们新的 MDX集成 (EN)。
要启用这一行为,请在 astro.config.mjs
配置文件中将 legacy.astroFlavoredMarkdown
设置为 true
。