Nue 项目结构详解从文件目录到 URL 的文件式路由体系【免费下载链接】nueFastest way to build modern websites项目地址: https://gitcode.com/GitHub_Trending/nu/nueNue 采用文件式路由系统项目目录结构直接映射为网站 URL无需任何路由配置文件。本篇指南以官方文档 project-structure.md 为核心结合仓库内minimal、blog、spa、full四个模板与官网packages/www的真实布局系统讲解 Nue 如何从最简单的两文件站点扩展到包含设计系统、后端与单页应用的大型项目。读完你将掌握 Nue 目录组织的全部约定、各类文件的处理规则以及可复用的工程化目录范式。工作原理文件即 URLNue 的核心设计哲学是目录结构即站点结构。文件系统层级与访问路径一一对应无需注册路由、无需配置文件index.html → / about.html → /about blog/index.html → /blog/ blog/first-post.md → /blog/first-post/规则非常简单任何 HTML 或 Markdown 文件都会成为一个页面CSS 文件成为样式表其余文件原样透传不做处理。这意味着你新增内容的方式就是新建文件删除内容的方式就是删除文件——站点结构始终与目录结构保持同步不存在文件存在但路由未注册的中间状态。从最小项目开始零配置起步Nue 提供项目脚手架命令minimal模板是体验零摩擦理念的最佳入口nue create minimal生成的结构只有两个文件├── index.css └── index.html仓库中该模板的真实内容印证了这种极简主义packages/templates/minimal/index.html 仅有h1Hello, World!/h1 pWelcome to extreme simplicity and performance/p没有配置文件、没有脚手架仪式、没有任何 setup 步骤——在浏览器中直接打开index.html就是一个可用的站点。这演示了 Nue 的核心理念你的项目结构就是你的站点结构。内容型站点Blog 模板nue create blog生成一个以内容为中心的站点包含共享布局与自动化的文章集合├── site.yaml # 站点配置 ├── layout.html # 全局页头与页脚 ├── index.css ├── index.md └── posts/ ├── header.html # 页面头部hero 布局 ├── first.md └── second.mdlayout.html提供所有页面的公共结构posts/存放 Markdown 内容site.yaml负责配置集合collection与元数据。仓库中 packages/templates/blog/site.yaml 展示了这一配置的完整形态meta: title: Emma Bennet / Design Engineering Blog title_template: %s / Emma Bennet author: Emma Bennet site: origin: https://acme.org view_transitions: true rss: enabled: true title: Acme blog description: Latest news on web development collection: blog design: inline_css: true collections: blog: include: [ posts/ ] require: [ title ] sort: date desc这里的collections.blog配置定义了文章集合的获取方式include: [posts/]表示抓取posts/目录下的所有 Markdown 文件require: [title]强制每篇文章必须提供标题字段sort: date desc按日期倒序排列。集合名blog会直接成为 HTML 模板中的变量——例如 packages/templates/blog/index.html 用:eachpage in blog遍历全部文章并渲染链接列表ul li :eachpage in blog a href{ page.url } ptime{ formatDate(page.date) }/time/p h3{ page.title }/h3 p{{ markdown(page.description) }}/p /a /li /ul关于集合的更多参数tags、skip、require等可参考 configuration.md。单页应用SPA 模板nue create spa生成一个完整的客户端应用结构. ├── css │ ├── base.css │ └── components.css ├── index.html ├── server │ ├── data │ │ └── users.json │ └── index.js ├── site.yaml └── ui └── lib.htmlindex.html控制路由与状态ui/存放页面级组件server/users.json成为 CloudFlare 兼容的数据存储server/index.js定义后端路由。仓库中的 packages/templates/spa/index.html 展示了 SPA 入口的关键写法!doctype dhtml script import { state } from state state.setup({ route: /:id, autolink: true }) /script body main article/ /main script state.on(id, ({ id }) { this.mount(id ? user : users, article) }) mounted() { state.init() } /script /body!doctype dhtml声明配合body作用域让该文件接管目录内所有路由route: /:id捕获 URL 参数this.mount()根据状态动态挂载不同组件。SPA 的完整开发流程数据模型、组件、路由串联参见 single-page-apps.md 与 spa-development.md。大型项目full 模板与 shared/ 系统目录nue create full对于严肃的应用程序shared/目录将应用的基础设施与各个应用分离。这种划分实现了应用的装配assembly能力——应用只关注结构HTML/Markdown其余所有职责设计、行为、逻辑、数据由系统层承担├── shared/ # 集中式系统 ├── app/ # 应用页面 ├── blog/ # 内容区域 ├── contact/ ├── docs/ ├── img/ ├── login/ ├── index.md ├── 404.md └── site.yaml仓库中的 packages/templates/full/ 正是这一布局的完整落地其shared/下同时包含design/、lib/、server/、ui/、data/五个子目录官网 packages/www/ 也是同样的组织方式shared/、blog/、docs/、home/、img/并列根级存放404.md、index.md、site.yaml与app.yaml。系统目录固定名称与特殊行为以下目录名称是硬编码的具有特殊处理逻辑shared/ ├── design/ # CSS 设计系统客户端自动加载 ├── ui/ # UI 组件。服务端与客户端均可使用客户端自动加载 ├── data/ # 供 HTML 模板使用的 YAML 数据服务端处理 └── server/ # 后端代码不属于前端资源design/中的 CSS 会被客户端自动加载ui/中的组件既能用于服务端渲染也能用于客户端data/中的 YAML 数据在服务端注入模板server/存放后端逻辑不会被打包进前端资源。推荐目录命名约定而非硬编码以下目录遵循命名约定但不是硬编码的shared/ ├── lib/ # 需要导入的第三方库 └── app/ # 业务逻辑 / 数据模型被导入建议在site.yaml的 import map 中登记它们例如# In site.yaml import_map: app: /shared/app/index.js lib: /shared/lib/配置之后前端代码即可使用干净简洁的导入语句import { login } from app // shared/app/index.js import * as d3 from lib/d3 // shared/lib/d3.js仓库中 packages/templates/full/site.yaml 给出了真实示例import_map: crud: /shared/lib/crud.js admin: /admin/admin.js与之呼应packages/templates/full/shared/lib/crud.js正是被import_map指向的通用 CRUD 模块。当系统层统一承担设计、行为与逻辑后应用开发只需聚焦内容与结构。随着网站/业务增长系统层保持简单不会因为业务膨胀而失控。应用 UI 文件夹如果某个应用拥有多个 CSS/JS 资源应将它们放入应用内部的ui文件夹如blog/ui而不是堆在应用根目录。这与shared/ui的分层逻辑一致系统级组件放在共享层应用私有资源留在应用层。Home 文件夹首页资源可以放入home文件夹与跨应用共享的根级资源分离。官网 packages/www/home/ 即包含app.yaml与home.css而共享样式放在根级shared/ui/global-layout.css等文件中正是这一约定的实际应用。文件类型每种扩展名的职责Nue 对不同文件类型有明确分工文件用途.html页面、组件与布局.md使用 Nuemark 语法的内容.css样式表自动加载.js客户端 JavaScript.tsTypeScript转译为 JavaScript.svg图形通过app.yaml配置处理.yaml配置与数据404.md/404.html自定义错误页面.html文件的具体行为由文档类型声明决定!doctype html是服务端渲染页面、!doctype dhtml是客户端动态页面、!html lib/!dhtml lib是组件库、!htmldhtml是同构组件详见 html-file-types.md。而资源的自动加载机制系统级 → 根级 → 应用级 → 页面级在 page-dependencies.md 中有完整说明。路由规则文件名决定路径文件名直接决定路由index.*文件映射目录本身其他文件映射为具体路径index.html → / about.md → /about/ contact/index.md → /contact/ contact/thanks.md → /contact/thanks app/index.html → /app/ (处理所有 /app/* 路由) admin/index.html → /admin/ (处理所有 /admin/* 路由) 404.md → 自定义错误页面两个值得注意的规则SPA 目录接管app/index.html与admin/index.html这样的入口会接管其目录下的所有子路由——这是 SPA 文件式路由的体现配合!doctype dhtml声明一个文件即可响应整个目录树的任意路径自定义错误页根目录放置404.md或404.html即可启用自定义错误页面。仓库中 packages/templates/full/404.md 与 packages/www/404.md 都是这一约定的实例。目录约定的实际验证上述约定并非停留在文档层面官网 packages/www/ 本身就是活生生的案例根级index.md映射首页、404.md提供错误页、site.yaml定义站点级配置、shared/承载设计系统与共享组件、blog/与docs/作为内容区分别拥有自己的app.yaml。app.yaml属于应用级配置可覆盖站点级设置三级配置体系站点 → 应用 → 页面的完整参数说明参见 configuration.md。小结Nue 的项目结构可以概括为一条主线加四个模板一条主线目录即路由——任何 HTML/Markdown 文件自动成为页面minimal两个文件体验零配置起步blogposts/site.yaml集合配置驱动内容站点spaindex.html入口 ui/组件 server/后端一个文件接管整个目录路由fullshared/系统层分离基础设施与业务应用design/、ui/、data/、server/各司其职配合import_map实现干净的模块导入。从最小站点到企业级应用Nue 用一套始终一致的目录约定完成了扩展这正是其项目结构即站点结构哲学的完整落地。【免费下载链接】nueFastest way to build modern websites项目地址: https://gitcode.com/GitHub_Trending/nu/nue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
