企业官网建设流程全解析

LikeC4 项目配置文件完全指南：从最小配置到多项目架构

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4

LikeC4 的软件架构图由.c4源文件与一个配置文件共同定义，配置文件是项目的"入口"与"总控台"——它决定了项目的作用域、名称、样式主题、图片别名、自动视图策略以及自定义生成器等一切行为。本指南以官方配置参考文档（configuration.md）为核心骨架，结合仓库packages/config的源码实现（schema.ts、load-config.ts 等）与 examples 目录中的真实配置示例，帮助你掌握每一种配置项的语义、默认值与边界约束，并能立即写出可运行的多项目架构配置。

配置文件的作用域与命名约定

LikeC4 项目的边界由配置文件的位置决定：配置所在目录（含所有子目录）内的全部.c4文件都属于该配置定义的项目。这个约定直接决定了你在仓库中如何组织架构源文件——把likec4.config.json放在某个目录下，就等于声明"从这里往下都是我的架构"。

LikeC4 会按任意顺序识别以下配置文件名称（源码实现在 filenames.ts 的ConfigFilenames常量中）：

说明：官方参考文档列出了 JSON/JS/TS 三种主格式；源码 filenames.ts 还额外支持likec4.config.cjs与likec4.config.cts两个 CommonJS 变体，可用于无法使用 ESM 的旧环境。

非 JSON 配置文件（JS/TS）相比 JSON 配置多了两个能力：可以编写自定义generators（生成器），以及在加载时通过 bundle-require 与 esbuild 打包执行，因此可以在配置中引用其他模块与变量。

JSON 配置 Schema：永远带上$schema

JSON 配置文件推荐（官方建议）始终包含$schema字段，它指向 LikeC4 官方 JSON Schema，可让 IDE 获得完整的校验与自动补全：

{ "$schema": "https://likec4.dev/schemas/config.json", "name": "my-project" }

源码层面，配置对象由 Zod v4 的LikeC4ProjectJsonConfigSchema（schema.ts）严格解析，并经过validateProjectConfig校验；JSON5 格式的解析由 parseProjectConfigJSON 完成（内部使用JSON5.parse），因此你的 JSON 文件可以带注释、允许尾逗号。

一个常见误区是省略$schema：

// ❌ 缺少 $schema —— IDE 无法提供校验与自动补全 { "name": "my-project" } // ✅ 正确 —— 带上 schema 获得 IDE 支持 { "$schema": "https://likec4.dev/schemas/config.json", "name": "my-project" }

全部配置项详解

name（必填）

项目唯一标识。约束严格，源码中通过两个refine校验（schema.ts）：

• 不能为空字符串；
• 不能是"default"（default是保留名）；
• 不能包含.、@、#这三个字符，官方提示"尽量使用 A-z、0-9、_和-"。

{ "name": "cloud-platform" }

title

人类可读的项目标题，会展示在生成的站点、IDE 与图表面板中。若填写则不能为空字符串：

{ "name": "cloud-platform", "title": "Cloud Platform Architecture" }

metadata

任意的键值对，用于记录自定义项目信息，例如归属团队、业务域、版本号。它是z.record(z.string(), z.any())，值可以是任意 JSON 类型：

{ "metadata": { "owner": "platform-team", "domain": "payments", "version": "2.0" } }

contactPerson

参与创建或维护该项目的人员，字符串类型，填写时不能为空：

{ "contactPerson": "Jane Doe" }

include

引用外部目录中额外的.c4文件，用于跨项目共享模型。各子项及其默认值、约束（源码在 schema.include.ts）：

{ "include": { "paths": ["../shared", "../common/specs"], "maxDepth": 5, "fileThreshold": 50 } }

提示：maxDepth与fileThreshold的边界值（1–20、1–10000）以及默认值均可在 schema.include.ts 中核实。若include配置整体非法，LikeC4ProjectConfigOps.normalizeInclude会回退到{ paths: [], maxDepth: 3, fileThreshold: 30 }。

exclude

用 picomatch 风格的 glob 模式排除文件。默认值为["**/node_modules/**"]：

{ "exclude": ["**/node_modules/**", "**/generated/**"] }

inferTechnologyFromIcon

当元素没有显式设置technology时，是否从图标名自动推导技术栈。作用于aws:、azure:、gcp:、tech:前缀的图标（bootstrap 图标除外）。默认true：

{ "inferTechnologyFromIcon": false }

implicitViews

为没有显式视图的元素自动生成作用域视图，从而支持"下钻"导航。默认false：

{ "implicitViews": true }

imageAliases

为图片目录路径定义快捷别名。默认别名@指向./images。源码（schema.image-alias.ts）规定：别名键必须以@开头（匹配/^@[A-Za-z0-9_-]*$/），值必须是相对路径（不允许前导/、盘符或协议）：

{ "imageAliases": { "@": "./images", "@shared": "../../shared-images" } }

manualLayouts

配置手动布局数据的存储位置。outDir相对于配置文件所在目录，默认".likec4"（源码见 schema.ts）：

{ "manualLayouts": { "outDir": ".likec4" } }

仓库示例 examples/multi-project/projectA/likec4.config.json 演示了将布局输出到.likec4/layouted子目录的用法。

styles

主题定制与默认样式，是配置项中最丰富的一个，其完整 Schema 在 schema.theme.ts 中定义。结构分三部分：

{ "styles": { "theme": { "colors": { "primary": "#FF6B6B", "secondary": "rgba(37,99,235,1)" } }, "defaults": { "border": "dashed", "opacity": 100, "size": "md", "relationship": { "color": "gray", "line": "dashed" } } } }

结合源码补充细节：

• theme.colors：可覆盖主题色。颜色值支持任意合法 CSS 颜色格式（hex、rgb、rgba、hsl、hsla 等），或拆分为更细的取值结构：elements（fill填充、stroke描边、hiContrast高对比文字/标题色、loContrast低对比文字/描述色）与relationships（line线条色、label标签文字色、labelBg标签背景色，默认rgba(0, 0, 0, 0.5)）。ThemeColorValuesSchema的computeColorValues转换逻辑见 schema.theme.ts。
• theme.sizes：覆盖各尺寸（sm/md/lg等）的width/height尺寸，宽高均要求不小于 50。
• defaults：元素的默认样式兜底值——color（必须是主题中存在的颜色名）、opacity（0–100 整数）、border（solid/dashed/dotted等）、size、shape、iconPosition，以及嵌套的group（组的color/opacity/border）与relationship（关系的color/line/arrow）。
• customCss（源码新增能力，官方参考文档未列）：一个 CSS 文件路径或路径数组，会被包含进生成的图表中，用于深度自定义渲染样式。

仓库中 examples/multi-project/dyn-config/likec4.config.mjs 展示了在 TS/JS 配置里组合styles.defaults.opacity: 10的写法。

extends

从其他配置文件（仅 JSON）继承样式。值为单个路径或路径数组。注意：extends只合并styles，其余字段以本配置文件为准：

{ "extends": "../shared/likec4.config.json" } { "extends": ["../shared/base.json", "../shared/theme.json"] }

加载机制的实现值得关注：load-config.ts 会递归解析extends链，将链上所有配置的styles用defu合并（链末端的配置优先级最高，见 load-config.ts），并且内置了循环引用检测——若 A extends B 且 B extends A，会抛出Config extends cycle detected: A -> B -> A错误。仓库 examples/multi-metadata-extend 目录演示了通过extends与多份配置叠加元数据的场景。

landingPage

配置生成站点的着陆页行为，三种互斥形式（LandingPageSchema见 schema.ts）：

重定向到索引视图：

{ "landingPage": { "redirect": true } }

只展示指定视图（include列表不可为空，选择器不能是"#"）：

{ "landingPage": { "include": ["overview", "cloud-detail"] } }

隐藏指定视图：

{ "landingPage": { "exclude": ["internal-debug"] } }

generators（仅 TypeScript/JS 配置可用）

自定义生成器：从模型产生任意输出文件。这是非 JSON 配置独有的能力，借助 defineConfig 获得完整的类型推导与运行时校验：

import { defineConfig } from 'likec4' export default defineConfig({ name: 'my-project', generators: { 'my-gen': async ({ likec4model, ctx }) => { const elements = likec4model.elements() await ctx.write({ path: 'output.json', content: JSON.stringify(elements, null, 2), }) }, }, })

运行生成器：likec4 gen my-gen（VSCode 中对应命令为LikeC4: Run code generator）。

生成器函数接收{ likec4model, ctx }两个参数（类型定义在 schema.ts）：likec4model是完整的 LikeC4 模型（可枚举元素、关系、视图）；ctx提供write()（写出文件，路径相对项目目录，自动创建目录）、locate()（定位任意元素/关系/视图在源文件中的精确位置）与abort()。仓库 examples/multi-project/dyn-config/likec4-generators.mjs 是一个可直接运行的示例：它为每个视图生成一个 JSON 快照文件到源文件同级的views/目录。也可以配合defineGenerators将生成器抽成独立模块复用，见 define-config.ts。

webapp（源码新增能力）

官方参考文档未列出的补充配置项，见 schema.ts，用于控制生成 Web 应用的行为：

• exportFormats：启用的导出格式数组，取自['png', 'jpg', 'dot', 'd2', 'mmd', 'puml', 'drawio']（见 webapp-export-formats.ts）。省略则启用全部；传空数组则禁用 Web 应用导出；不允许重复项。
• relationshipsBrowser.defaultScope：关系浏览器的默认作用域，取'global'或'view'，默认'view'。

多项目（Multi-Project）设置

工作区内每个配置文件定义一个独立项目；目录层级中距离最近的配置文件决定.c4文件归属哪个项目：

workspace/ ├─ project-a/ │ ├─ likec4.config.json ← project "a" │ ├─ model.c4 │ └─ views.c4 ├─ project-b/ │ ├─ likec4.config.json ← project "b" │ └─ model.c4 └─ shared/ └─ common.c4 ← 通过 "include.paths" 引入

跨项目共享.c4文件的推荐方式就是include.paths。仓库的 examples/multi-project 目录提供了完整的多项目样例，其中 projectA/likec4.config.json 与 projectB/architecture.c4 展示了两个独立项目如何并存，而dyn-config项目则演示了如何在 TS 配置中组合include、styles与generators。

另外需要注意一个加载细节：非 JSON 配置文件加载时，loadConfig会把配置所在目录名作为隐式name兜底（load-config.ts 中的implicitcfg = { name: basename(folder) }），也就是说即使你忘了写name，配置也不会直接失败——但请始终显式声明name，避免命名失控。

最小起步配置

一个可以直接复制使用的起点：

{ "$schema": "https://likec4.dev/schemas/config.json", "name": "my-project", "title": "My Architecture" }

重要提醒：务必包含"$schema"——它能为配置文件启用 IDE 自动补全与校验，避免手写配置时因拼写错误或取值越界（如opacity: 150、name含@）而踩坑。仓库中几乎每个示例都遵循这一约定，例如 examples/metadata-views/likec4.config.json。

配置加载与校验机制速览

了解配置是如何被读取的，有助于排查问题。核心入口是 loadConfig：

1. JSON/JSON5 配置：读取文件内容后经JSON5.parse解析（因此支持注释与尾逗号），递归解析extends链（含循环检测），合并styles，最后经validateProjectConfig严格校验。
2. 非 JSON 配置：通过bundleRequire+ esbuild 打包执行；为提升加载速度，load-config.ts 会把likec4/config的导入"拦截并替换"为轻量 mock（defineConfig等直接透传），避免重复打包整个 config 包。
3. 任何校验失败都会通过z.prettifyError输出可读的错误信息（如Config validation failed: ...），并抛出明确异常。

这些机制的单元测试覆盖在 schema.spec.ts 与 schema.theme.spec.ts 中，读者可以结合测试用例进一步理解各配置项的取值边界。

小结

配置文件是 LikeC4 项目的心脏：用name定义唯一身份，用include/exclude划定模型边界，用styles/extends统一视觉体系，用imageAliases管理图片资源，用implicitViews开启自动下钻，用landingPage控制站点入口，用generators把模型变成可编程的输出管道。结合 configuration.md 参考文档与packages/config源码，你现在应该能够为单项目、多项目乃至带自定义生成器的复杂场景写出准确、可维护的 LikeC4 配置。

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4