使用 Nitro 的 gitlab_pages 预设将应用部署到 GitLab Pages【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitroGitLab Pages 是 GitLab 官方提供的静态网站托管服务可以直接从 GitLab 仓库的 CI/CD 流水线发布站点。Nitro 内置了gitlab_pages预设让你无需编写服务端代码即可把基于 Nitro 构建的预渲染静态应用一键部署到 GitLab Pages。本文以 docs/2.deploy/20.providers/gitlab-pages.md 为主线结合仓库源码与测试完整讲解预设机制、CI 配置、自定义 404 页面与常见注意事项帮助读者在自己的 GitLab 项目中完成从构建到上线的全流程。前置准备创建一个 GitLab Pages 站点在部署 Nitro 应用之前需要先在 GitLab 侧完成 Pages 站点的初始化。官方给出的标准流程是在 GitLab 上创建或使用已有的项目在项目设置中确认 Pages 功能已启用新项目默认启用推送代码后通过.gitlab-ci.yml中的pagesjob 生成public目录下的静态文件GitLab 会自动将其发布为 Pages 站点站点地址通常形如https://namespace.gitlab.io/project或使用 GitLab 分配给项目的自定义域名。关联文档在 docs/2.deploy/20.providers/gitlab-pages.md 中明确要求先按照 GitLab 官方文档完成站点创建步骤本教程后续的所有配置都建立在这个前提之上。选择 gitlab_pages 预设在 Nitro 中部署目标通过预设preset来描述。每个预设定义了一套输出结构、预渲染规则和可选命令。GitLab Pages 对应的预设名为gitlab_pages在部分源码与配置中写作 kebab-case 形式gitlab-pages两者等价。在 src/presets/_static/preset.ts 中可以找到该预设的完整定义const gitlabPages defineNitroPreset( { extends: static, prerender: { routes: [ /, // https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages /404.html, ], }, }, { name: gitlab-pages as const, static: true, } );从源码结构可以看出gitlab_pages预设的两个关键设计继承自static预设extends: static意味着它复用静态输出的全部行为。static预设定义于 src/presets/_static/preset.ts其核心要点包括static: true构建产物只包含静态文件不产生服务端 bundle输出目录为{{ rootDir }}/.output公开文件位于.output/publicprerender.crawlLinks: true构建时会自动爬取页面内链接进行预渲染预览命令为npx serve ./public可在本地模拟线上静态托管。强制预渲染根路径与 404 页面prerender.routes固定包含/和/404.html。其中/404.html是 GitLab Pages 的自定义错误页约定——静态托管服务无法在请求 404 时执行服务端逻辑只能回落到一个预先生成的404.html文件。注意gitlab_pages预设并未像github-pages预设见 src/presets/_static/preset.ts那样注册compiledhook 写入.nojekyll文件因为 GitLab Pages 不执行 Jekyll 处理不需要这个步骤。预设名称的统一管理位于 src/presets/_types.gen.tsPresetName类型中同时列出了gitlab-pages与github-pages。预设的注册与解析逻辑在 src/presets/_resolve.ts构建时Nitro 会把传入的预设名统一转换为 kebab-casegitlab_pages→gitlab-pages再在_all.gen.ts见 src/presets/_all.gen.ts汇总的全部预设中做匹配最终找到gitlab-pages预设并使用其static: true元信息参与后续的静态构建流程。编写 .gitlab-ci.yml 完成部署关联文档给出了完整的 GitLab CI/CD 配置这是整个部署流程的核心。以下逐段拆解这份配置image: node:lts before_script: - npx nypm install pages: cache: paths: - node_modules/ variables: NITRO_PRESET: gitlab_pages script: - npm run build artifacts: paths: - .output/public publish: .output/public rules: # This ensures that only pushes to the default branch # will trigger a pages deploy - if: $CI_COMMIT_REF_NAME $CI_DEFAULT_BRANCH配置段作用与说明image: node:lts使用 Node.js LTS 官方镜像作为 CI 运行环境保证npm、npx等命令可用。before_script: npx nypm installnypm是跨包管理器的统一安装工具它会自动识别项目中的package.json/pnpm-lock.yaml等文件并执行对应安装命令避免在 CI 中手动区分npm/pnpm/yarn。cache.paths: node_modules/缓存依赖目录加速后续流水线的构建。variables.NITRO_PRESET: gitlab_pages通过环境变量显式指定 Nitro 预设。这是 CI/CD 场景下官方推荐的预设指定方式。script: npm run build执行构建命令对应的package.json脚本通常为build: nitro build。artifacts.paths: .output/publicpublish: .output/public将.output/public目录作为产物上传并让 GitLab Pages 直接发布该目录。GitLab Pages 约定发布目录名必须为public这里通过publish字段将实际产物目录.output/public指向它。rules只在默认分支如main的推送触发 Pages 部署避免在功能分支上浪费构建资源。为什么是 NITRO_PRESET 环境变量在 CI 环境中通过NITRO_PRESET指定预设是因为 Nitro 的配置加载器会按固定优先级读取预设来源。查看 src/config/loader.tslet preset: string | undefined (configOverrides.preset as string) || process.env.NITRO_PRESET || process.env.SERVER_PRESET;即预设来源优先级为命令行/代码中传入的preset配置 NITRO_PRESET环境变量 SERVER_PRESET环境变量。在 CI 中NITRO_PRESET是最简单、最不易出错的指定方式也便于在不同流水线中复用同一份代码。除了环境变量还有另外两种等价方式使用 CLI 参数见 src/cli/commands/build.ts 中--preset参数的定义nitro build --preset gitlab_pages在 nitro.config.ts 中配置preset字段import { defineConfig } from nitro; export default defineConfig({ preset: gitlab_pages, });三种方式的优先级与适用范围可参考 docs/2.deploy/0.index.md 中Changing the deployment preset一节的说明环境变量方式最适合 CI/CD 部署。本地验证与产物检查在推送到 GitLab 之前建议先在本地完成构建验证避免流水线反复失败# 使用 gitlab_pages 预设构建 NITRO_PRESETgitlab_pages npm run build # 检查产物结构 ls -la .output/public预期产物包含index.html预渲染的首页由prerender.routes中的/生成404.htmlGitLab Pages 自定义错误页由预设自动加入预渲染路由其他静态资源与爬取到的页面。这一行为有对应的测试用例佐证。在 test/vite/static-preset.test.ts 中测试框架对static/github-pages等静态预设执行真实构建并断言serverDir不存在即没有服务端 bundle 产出does not emit a server bundlepublic目录下存在index.html且包含预渲染内容prerenders routes to the public dir。gitlab-pages与它们共用同一套static基座行为一致该测试文件第 15 行注释中保留了gitlab-pages的登记项。构建成功后可将.output/public的内容用于本地静态预览npx serve .output/public静态托管的局限性与注意事项gitlab_pages是纯静态预设它带来便利的同时也有明确边界理解这些限制有助于避免部署后的翻车无服务端运行时GitLab Pages 只托管静态文件不执行 Node.js。API 路由、server目录下的服务端逻辑、WebSocket 等能力不会生效。适合纯前端站点、预渲染内容、或与外部 API 服务配合的场景。预渲染是唯一渲染路径页面必须在构建期被预渲染为 HTML。prerender.crawlLinks: true见static预设定义会自动爬取内链但动态内容、客户端渲染后才会出现的内容无法被静态化。对于需要动态数据的页面可以考虑 SSG 数据注入或改用手动声明的prerender.routes。404 页面需提前预渲染/404.html由预设自动加入路由请不要在prerender.routes中移除它若想自定义错误页样式在server/routes/404.html或对应渲染方式中提供内容即可。GitLab Pages 的自定义域名与 HTTPS站点绑定自定义域名、启用 HTTPS 需要在 GitLab 项目设置中操作与 Nitro 构建无关。rules限制触发分支文档中的配置只在默认分支触发部署。如果使用workflow_dispatch或需要手工部署需要自行调整 rules。常见问题排查站点 404 或空白页先确认 CI 产物中是否存在.output/public/index.html且publish: .output/public配置正确。GitLab Pages 强制要求发布目录名为public所以publish字段必须指向名为public的目录。构建产物含服务端文件检查是否真的指定了gitlab_pages预设。若NITRO_PRESET未生效如被nitro.config.ts中的preset字段覆盖会退回到默认的node-server预设产物将包含服务端 bundle无法被 Pages 正确发布。依赖安装慢或失败确认package.json中已声明nitro依赖并合理使用 CI 缓存cache.paths: node_modules/。npx nypm install会根据锁文件选择正确的包管理器。404 页面未生效检查最终.output/public中是否生成了404.html。该文件由gitlab_pages预设自动预渲染如果手动覆盖了prerender.routes请务必保留/404.html。总结Nitro 的gitlab_pages预设让 GitLab Pages 部署变得极其轻量一份.gitlab-ci.yml、一个环境变量即可完成。其底层实现src/presets/_static/preset.ts继承了static预设的静态输出与链接爬取能力并针对 GitLab Pages 自动加入/404.html预渲染通过 src/config/loader.ts 的预设优先级设计NITRO_PRESET可以在不修改任何配置代码的情况下切换部署目标。如果你的应用以静态内容、预渲染页面为主这是将 Nitro 项目发布到 GitLab 生态最直接的方式。关于预设的更多通用机制零配置自动检测、compatibilityDate 等可进一步阅读 docs/2.deploy/0.index.md。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Nitro 的 gitlab_pages 预设将应用部署到 GitLab Pages
使用 Nitro 的 gitlab_pages 预设将应用部署到 GitLab Pages【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitroGitLab Pages 是 GitLab 官方提供的静态网站托管服务可以直接从 GitLab 仓库的 CI/CD 流水线发布站点。Nitro 内置了gitlab_pages预设让你无需编写服务端代码即可把基于 Nitro 构建的预渲染静态应用一键部署到 GitLab Pages。本文以 docs/2.deploy/20.providers/gitlab-pages.md 为主线结合仓库源码与测试完整讲解预设机制、CI 配置、自定义 404 页面与常见注意事项帮助读者在自己的 GitLab 项目中完成从构建到上线的全流程。前置准备创建一个 GitLab Pages 站点在部署 Nitro 应用之前需要先在 GitLab 侧完成 Pages 站点的初始化。官方给出的标准流程是在 GitLab 上创建或使用已有的项目在项目设置中确认 Pages 功能已启用新项目默认启用推送代码后通过.gitlab-ci.yml中的pagesjob 生成public目录下的静态文件GitLab 会自动将其发布为 Pages 站点站点地址通常形如https://namespace.gitlab.io/project或使用 GitLab 分配给项目的自定义域名。关联文档在 docs/2.deploy/20.providers/gitlab-pages.md 中明确要求先按照 GitLab 官方文档完成站点创建步骤本教程后续的所有配置都建立在这个前提之上。选择 gitlab_pages 预设在 Nitro 中部署目标通过预设preset来描述。每个预设定义了一套输出结构、预渲染规则和可选命令。GitLab Pages 对应的预设名为gitlab_pages在部分源码与配置中写作 kebab-case 形式gitlab-pages两者等价。在 src/presets/_static/preset.ts 中可以找到该预设的完整定义const gitlabPages defineNitroPreset( { extends: static, prerender: { routes: [ /, // https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages /404.html, ], }, }, { name: gitlab-pages as const, static: true, } );从源码结构可以看出gitlab_pages预设的两个关键设计继承自static预设extends: static意味着它复用静态输出的全部行为。static预设定义于 src/presets/_static/preset.ts其核心要点包括static: true构建产物只包含静态文件不产生服务端 bundle输出目录为{{ rootDir }}/.output公开文件位于.output/publicprerender.crawlLinks: true构建时会自动爬取页面内链接进行预渲染预览命令为npx serve ./public可在本地模拟线上静态托管。强制预渲染根路径与 404 页面prerender.routes固定包含/和/404.html。其中/404.html是 GitLab Pages 的自定义错误页约定——静态托管服务无法在请求 404 时执行服务端逻辑只能回落到一个预先生成的404.html文件。注意gitlab_pages预设并未像github-pages预设见 src/presets/_static/preset.ts那样注册compiledhook 写入.nojekyll文件因为 GitLab Pages 不执行 Jekyll 处理不需要这个步骤。预设名称的统一管理位于 src/presets/_types.gen.tsPresetName类型中同时列出了gitlab-pages与github-pages。预设的注册与解析逻辑在 src/presets/_resolve.ts构建时Nitro 会把传入的预设名统一转换为 kebab-casegitlab_pages→gitlab-pages再在_all.gen.ts见 src/presets/_all.gen.ts汇总的全部预设中做匹配最终找到gitlab-pages预设并使用其static: true元信息参与后续的静态构建流程。编写 .gitlab-ci.yml 完成部署关联文档给出了完整的 GitLab CI/CD 配置这是整个部署流程的核心。以下逐段拆解这份配置image: node:lts before_script: - npx nypm install pages: cache: paths: - node_modules/ variables: NITRO_PRESET: gitlab_pages script: - npm run build artifacts: paths: - .output/public publish: .output/public rules: # This ensures that only pushes to the default branch # will trigger a pages deploy - if: $CI_COMMIT_REF_NAME $CI_DEFAULT_BRANCH配置段作用与说明image: node:lts使用 Node.js LTS 官方镜像作为 CI 运行环境保证npm、npx等命令可用。before_script: npx nypm installnypm是跨包管理器的统一安装工具它会自动识别项目中的package.json/pnpm-lock.yaml等文件并执行对应安装命令避免在 CI 中手动区分npm/pnpm/yarn。cache.paths: node_modules/缓存依赖目录加速后续流水线的构建。variables.NITRO_PRESET: gitlab_pages通过环境变量显式指定 Nitro 预设。这是 CI/CD 场景下官方推荐的预设指定方式。script: npm run build执行构建命令对应的package.json脚本通常为build: nitro build。artifacts.paths: .output/publicpublish: .output/public将.output/public目录作为产物上传并让 GitLab Pages 直接发布该目录。GitLab Pages 约定发布目录名必须为public这里通过publish字段将实际产物目录.output/public指向它。rules只在默认分支如main的推送触发 Pages 部署避免在功能分支上浪费构建资源。为什么是 NITRO_PRESET 环境变量在 CI 环境中通过NITRO_PRESET指定预设是因为 Nitro 的配置加载器会按固定优先级读取预设来源。查看 src/config/loader.tslet preset: string | undefined (configOverrides.preset as string) || process.env.NITRO_PRESET || process.env.SERVER_PRESET;即预设来源优先级为命令行/代码中传入的preset配置 NITRO_PRESET环境变量 SERVER_PRESET环境变量。在 CI 中NITRO_PRESET是最简单、最不易出错的指定方式也便于在不同流水线中复用同一份代码。除了环境变量还有另外两种等价方式使用 CLI 参数见 src/cli/commands/build.ts 中--preset参数的定义nitro build --preset gitlab_pages在 nitro.config.ts 中配置preset字段import { defineConfig } from nitro; export default defineConfig({ preset: gitlab_pages, });三种方式的优先级与适用范围可参考 docs/2.deploy/0.index.md 中Changing the deployment preset一节的说明环境变量方式最适合 CI/CD 部署。本地验证与产物检查在推送到 GitLab 之前建议先在本地完成构建验证避免流水线反复失败# 使用 gitlab_pages 预设构建 NITRO_PRESETgitlab_pages npm run build # 检查产物结构 ls -la .output/public预期产物包含index.html预渲染的首页由prerender.routes中的/生成404.htmlGitLab Pages 自定义错误页由预设自动加入预渲染路由其他静态资源与爬取到的页面。这一行为有对应的测试用例佐证。在 test/vite/static-preset.test.ts 中测试框架对static/github-pages等静态预设执行真实构建并断言serverDir不存在即没有服务端 bundle 产出does not emit a server bundlepublic目录下存在index.html且包含预渲染内容prerenders routes to the public dir。gitlab-pages与它们共用同一套static基座行为一致该测试文件第 15 行注释中保留了gitlab-pages的登记项。构建成功后可将.output/public的内容用于本地静态预览npx serve .output/public静态托管的局限性与注意事项gitlab_pages是纯静态预设它带来便利的同时也有明确边界理解这些限制有助于避免部署后的翻车无服务端运行时GitLab Pages 只托管静态文件不执行 Node.js。API 路由、server目录下的服务端逻辑、WebSocket 等能力不会生效。适合纯前端站点、预渲染内容、或与外部 API 服务配合的场景。预渲染是唯一渲染路径页面必须在构建期被预渲染为 HTML。prerender.crawlLinks: true见static预设定义会自动爬取内链但动态内容、客户端渲染后才会出现的内容无法被静态化。对于需要动态数据的页面可以考虑 SSG 数据注入或改用手动声明的prerender.routes。404 页面需提前预渲染/404.html由预设自动加入路由请不要在prerender.routes中移除它若想自定义错误页样式在server/routes/404.html或对应渲染方式中提供内容即可。GitLab Pages 的自定义域名与 HTTPS站点绑定自定义域名、启用 HTTPS 需要在 GitLab 项目设置中操作与 Nitro 构建无关。rules限制触发分支文档中的配置只在默认分支触发部署。如果使用workflow_dispatch或需要手工部署需要自行调整 rules。常见问题排查站点 404 或空白页先确认 CI 产物中是否存在.output/public/index.html且publish: .output/public配置正确。GitLab Pages 强制要求发布目录名为public所以publish字段必须指向名为public的目录。构建产物含服务端文件检查是否真的指定了gitlab_pages预设。若NITRO_PRESET未生效如被nitro.config.ts中的preset字段覆盖会退回到默认的node-server预设产物将包含服务端 bundle无法被 Pages 正确发布。依赖安装慢或失败确认package.json中已声明nitro依赖并合理使用 CI 缓存cache.paths: node_modules/。npx nypm install会根据锁文件选择正确的包管理器。404 页面未生效检查最终.output/public中是否生成了404.html。该文件由gitlab_pages预设自动预渲染如果手动覆盖了prerender.routes请务必保留/404.html。总结Nitro 的gitlab_pages预设让 GitLab Pages 部署变得极其轻量一份.gitlab-ci.yml、一个环境变量即可完成。其底层实现src/presets/_static/preset.ts继承了static预设的静态输出与链接爬取能力并针对 GitLab Pages 自动加入/404.html预渲染通过 src/config/loader.ts 的预设优先级设计NITRO_PRESET可以在不修改任何配置代码的情况下切换部署目标。如果你的应用以静态内容、预渲染页面为主这是将 Nitro 项目发布到 GitLab 生态最直接的方式。关于预设的更多通用机制零配置自动检测、compatibilityDate 等可进一步阅读 docs/2.deploy/0.index.md。【免费下载链接】nitroNext Generation Server Toolkit. Create web servers with everything you need and deploy them wherever you prefer.项目地址: https://gitcode.com/GitHub_Trending/ni/nitro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考