likec4 / likec4

#12

1,421119+29 todayTypeScript

View on GitHub

Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code

💡 Use Cases

最适合需要将软件架构作为代码管理、并自动生成实时、可协作、可定制化图表的中大型项目团队。

架构文档与代码脱节

Problem: 架构图（如Visio、draw.io绘制）与代码实际结构不同步，文档很快过时，维护成本高。

Solution: 使用LikeC4将架构定义为代码，通过CLI或CI/CD自动生成实时更新的图表，确保文档与代码一致。

Example: 在每次代码提交后，通过GitHub Actions运行likec4生成最新的架构图并更新到项目Wiki或部署为静态站点。

多层级架构可视化

Problem: 单一静态图难以清晰展示从系统上下文到代码组件（C4模型各级）的完整架构层次。

Solution: 利用LikeC4支持自定义嵌套层级的特性，用代码定义不同抽象层级的元素和关系，一键生成可交互的多层级架构图。

Example: 为微服务系统分别定义“系统上下文”、“容器”、“组件”三层模型，生成一个可缩放、点击切换层级的动态图表网站。

团队协作定义架构

Problem: 架构设计分散在会议、文档或不同人的脑中，缺乏统一、可版本化、可评审的单一事实来源。

Solution: 将架构模型像代码一样用LikeC4语言编写，存储在Git仓库中，支持代码评审、分支合并和变更追溯。

Example: 在开发新功能前，创建Git分支，用LikeC4语言添加或修改相关服务、接口的描述，提交Pull Request进行架构设计评审。

定制化架构视图

Problem: 标准C4模型或现有工具的元素类型、样式不符合团队内部规范或特定技术栈的表达需求。

Solution: 使用LikeC4灵活的建模语言，自定义元素类型、图标、颜色和关系线样式，生成完全贴合项目需求的专属架构图。

Example: 为Kubernetes项目自定义“Pod”、“Service”、“Ingress”等元素类型，并关联特定图标，生成云原生架构图。

📊 Project Info

Language: TypeScript
Stars: ⭐ 1,421
Forks: 119
Today: +29
Ranking: #12
Collection: Overall
Trending Date: February 4, 2026

🏷️ Topics

TypeScript架构可视化代码生成实时动态可定制软件架构师

📸 Screenshots

5分钟上手 LikeC4：从代码生成实时架构图

本指南将帮助你在5分钟内安装LikeC4并生成第一个架构图，体验'架构即代码'的魅力。

🖥️ OS

macOSWindowsLinux

⚙️ Runtime

Node.js>= 18.0

🔧 Tools

Git— 克隆示例项目模板

📝 Steps

克隆模板项目

LikeC4提供了开箱即用的模板项目，包含示例代码和配置，这是最快开始的方式。

克隆官方模板项目到本地

$ git clone https://github.com/likec4/template.git likec4-demo

进入项目目录

$ cd likec4-demo

✓Expected: 成功克隆后，你会看到包含src、.likec4等目录的项目结构。

💡如果网络较慢，也可以直接下载ZIP包解压。

安装依赖

LikeC4基于TypeScript开发，需要安装项目依赖。

安装所有依赖包

$ npm install

✓Expected: 看到类似'added 123 packages in 5s'的提示，表示安装成功。

💡如果安装缓慢，可以尝试使用npm config set registry https://registry.npmmirror.com

启动开发服务器

LikeC4提供实时预览功能，修改代码后图表会自动更新。

启动开发服务器

$ npm run dev

✓Expected: 看到类似'Server running at http://localhost:3000'的输出。

💡默认端口是3000，如果被占用会自动选择其他端口。

查看生成的架构图

打开浏览器查看LikeC4根据代码自动生成的架构图。

查看实时架构图

$ 打开浏览器访问 http://localhost:3000

✓Expected: 浏览器中显示一个完整的软件架构图，包含多个层级和组件。

💡可以尝试修改src目录下的.c4文件，保存后浏览器会自动刷新。

✅ 验证成功

成功运行LikeC4的标志

✓浏览器中显示完整的架构图
✓开发服务器正常运行无报错
✓修改.c4文件后图表自动更新

⚡ Quick Tips

配置所有架构定义都在src目录的.c4文件中，这是LikeC4的建模语言文件

其他按Ctrl+C可以停止开发服务器

配置模板项目已经配置好了TypeScript和构建脚本，可以直接使用

🔍 Troubleshooting

❓ npm install失败，提示权限问题

→ 不要使用sudo，可以运行npm config set prefix ~/.npm-global，或将当前用户加入node_modules目录的写权限

❓ 端口3000已被占用

→ 开发服务器会自动选择其他端口，查看终端输出中的实际端口号

❓ 浏览器中看不到图表，只显示空白页面

→ 检查终端是否有错误信息，确保所有依赖安装成功，尝试重新运行npm install

❓ Node.js版本过低

→ 使用nvm或直接下载安装Node.js 18或更高版本

🎯 Next Steps

查看官方教程

访问官方文档了解LikeC4建模语言的完整语法

修改示例代码

尝试修改src/目录下的.c4文件，观察图表如何实时变化

加入Discord社区

获取实时帮助和与其他用户交流

Difficulty

初级

Est. Time

3-4小时

Target Audience

对软件架构可视化感兴趣的开发者、技术负责人、架构师，尤其适合希望用代码维护架构文档的团队。无需预先掌握C4模型或Structurizr。

🎯 What You'll Learn

学会使用LikeC4语言描述软件架构，并通过命令行工具生成实时、可交互的架构图，实现架构文档的代码化管理。

📋 Prerequisites

TypeScript/JavaScript基础了解

LikeC4使用TypeScript作为建模语言，需要能理解基本的变量、函数和对象语法。

Node.js与npm/yarn/pnpm了解

需要安装Node.js环境来运行LikeC4 CLI工具和初始化项目。

Git基础了解

用于克隆模板仓库或管理自己的LikeC4项目代码。

C4模型或软件架构图概念了解(optional)

有助于理解LikeC4的设计理念，但不是必须的，可以在学习中逐步了解。

📚 Resources

必看

LikeC4 官方文档

全面的语言规范、API参考和概念解释。

必看

项目README中的Tutorial链接

快速概览LikeC4的实战教程。

🗺️ Learning Phases

环境准备与初体验

⏱ 30分钟

安装Node.js

确保你的电脑上安装了Node.js（建议LTS版本）。可以在终端运行 `node --version` 和 `npm --version` 检查是否安装成功。

💡如果未安装，请前往Node.js官网下载安装包。

在线体验（零安装）

访问项目README中提到的Playground（https://stackblitz.com/~/github.com/likec4/template）或Demo站点。直接在浏览器中查看和修改示例代码，观察图表如何实时变化，感受LikeC4的核心工作流程。

💡这是最快、最安全的入门方式，强烈建议先从这里开始，建立直观感受。

创建第一个本地项目

⏱ 1小时

使用模板项目

按照README指引，使用Git克隆模板仓库：`git clone https://github.com/likec4/template.git my-likec4-project`，然后进入项目目录 `cd my-likec4-project`。

💡模板项目已经配置好了所有依赖和示例文件，是学习的最佳起点。

安装依赖并启动开发服务器

在项目根目录下运行 `npm install` 或 `pnpm install` 或 `yarn` 安装依赖。安装完成后，运行 `npm run dev` 启动本地开发服务器。

💡如果安装缓慢，可以考虑切换npm源或使用pnpm。

查看并修改示例

打开浏览器访问 `http://localhost:3000`。同时，用代码编辑器打开 `src` 目录下的 `.c4` 文件（如 `index.c4`）。尝试修改文件中的一些文本（如元素名称、描述），保存后观察浏览器中的图表是否实时更新。

💡重点关注 `element`、`relationship` 等关键词，理解它们如何对应到图中的组件和连线。

学习核心建模概念

⏱ 1.5小时

理解基本元素（Element）

在示例代码中，找到用 `element` 关键字定义的部分。尝试创建一个新的元素，例如 `element mobileApp = 'Mobile App'`。理解 `=` 后面的字符串是标题，还可以在花括号 `{}` 内添加 `description`、`technology` 等属性。

💡元素是架构图的基石，可以代表系统、容器、组件等任何东西。

建立关系（Relationship）

找到用 `relationship` 关键字定义的部分。尝试在两个已存在的元素之间建立一条新的关系，例如 `relationship(mobileApp, api, '使用HTTPS调用', 'HTTPS')`。保存后查看图中是否出现了新的箭头。

💡关系的定义顺序是 `从(源)` -> `到(目标)`。

探索视图（View）与层级

找到以 `view` 开头的代码块。这是定义特定视角图表的地方。尝试修改 `of` 后面的元素名称，或者调整 `include` 包含的元素范围，观察生成的图表变化。

💡视图让你可以聚焦于架构的特定部分，例如系统上下文图或某个容器内部的组件图。

运行构建，生成静态图表

在终端中运行 `npm run build`。完成后，查看生成的 `dist` 目录。这里包含了可以独立部署的静态网站和图表。

💡这展示了LikeC4不仅用于开发时预览，也能生成最终交付物。

下一步实践与探索

⏱ 30分钟

尝试描述你自己的简单项目

新建一个 `.c4` 文件，尝试用3-5个元素和若干关系，描述一个你熟悉或正在开发的小型系统（例如一个博客网站）。然后创建一个视图来展示它。

💡从最顶层的系统上下文开始画起，逐步细化。不要追求完美，先跑通流程。

查阅官方文档与教程

访问项目README中提到的 `docs` 和 `Tutorial` 链接，系统学习更高级的特性，如自定义样式、标签、动态视图等。

💡官方文档是深入学习的最佳资源，遇到问题先来这里查找。

⚠️ Common Mistakes

❌ 在`.c4`文件中使用JavaScript/TypeScript的高级语法。

✅ LikeC4有自己的领域特定语言(DSL)语法，虽然基于TS，但并非完全一致。严格遵循文档中的示例格式，尤其是元素和关系的定义方式。

❌ 元素名称重复或使用了非法字符。

✅ 元素标识符（`=`左边的名字）必须是唯一的，且遵循编程语言变量名的常规约定（避免空格、特殊字符）。标题（`=`右边的字符串）可以重复。

❌ 修改代码后，浏览器图表没有自动刷新。

✅ 1. 确保开发服务器 (`npm run dev`) 正在运行。2. 确保保存了`.c4`源文件。3. 检查终端或浏览器控制台是否有错误信息。4. 尝试手动刷新浏览器页面。

❌ 试图在视图（view）中包含未定义或不存在的元素。

✅ 视图的 `of` 和 `include` 中引用的元素，必须事先用 `element` 关键字正确定义。检查拼写和范围（是否在同一个文件或通过import引入）。

🚀 Next Steps

学完基础后可以继续探索的方向