n8n 开发规范与最佳实践指南 | TypeScript、Vue 3、后端架构

n8n-conventions by n8n-io/n8n

274 周安装量

181,100 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/n8n-io/n8n --skill n8n-conventions

自动化 TypeScript 代码规范

🇨🇳中文介绍

n8n 快速参考

📚 完整文档：

通用： /AGENTS.md - 架构、命令、工作流
前端： /packages/frontend/AGENTS.md - CSS 变量、时序

当你需要快速回忆关键模式时，请使用此技能。

关键规则（必须遵守）

TypeScript：

永远不要使用 any → 使用 unknown
优先使用 satisfies 而非 as（测试除外）
共享类型放在 @n8n/api-types 中

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

104,600 周安装

GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题

22,500 周安装

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

22,200 周安装

import { UnexpectedError } from 'n8n-workflow';
throw new UnexpectedError('message', { extra: { context } });
// 不要使用已弃用的 ApplicationError

Vue 3 组合式 API (<script setup lang="ts">)
CSS 变量（切勿硬编码 px） - 参见 /packages/frontend/AGENTS.md
所有文本通过 i18n ($t('key')) 处理
为 E2E 测试使用 data-testid（单一值，无空格）

Controller → Service → Repository 分层结构
通过 @n8n/di 进行依赖注入
通过 @n8n/config 进行配置
使用 Zod 模式进行验证

Vitest（单元测试），Playwright（E2E 测试）
模拟外部依赖
在包目录下工作：pushd packages/cli && pnpm test

仅使用 SQLite/PostgreSQL（应用数据库）
例外：数据库节点（如 MySQL 节点等）可以使用特定数据库的功能

pnpm build > build.log 2>&1  # 始终重定向输出
pnpm typecheck               # 提交前运行
pnpm lint                    # 提交前运行

包	用途
`packages/cli`	后端 API
`packages/frontend/editor-ui`	Vue 3 前端
`packages/@n8n/api-types`	共享类型
`packages/@n8n/db`	TypeORM 实体
`packages/workflow`	核心接口

import { STORES } from '@n8n/stores';
export const useMyStore = defineStore(STORES.MY_STORE, () => {
  const state = shallowRef([]);
  return { state };
});

<script setup lang="ts">
type Props = { title: string };
const props = defineProps<Props>();
</script>

import { Service } from '@n8n/di';
import { Config } from '@n8n/config';

@Service()
export class MyService {
  constructor(private readonly config: Config) {}
}

📖 需要更多细节？ 阅读 /AGENTS.md 和 /packages/frontend/AGENTS.md

🇺🇸English

n8n Quick Reference

📚 Full Documentation:

General: /AGENTS.md - Architecture, commands, workflows
Frontend: /packages/frontend/AGENTS.md - CSS variables, timing

Use this skill when you need quick reminders on critical patterns.

Critical Rules (Must Follow)

TypeScript:

Never any → use unknown
Prefer satisfies over as (except tests)
Shared types in @n8n/api-types

Error Handling:

import { UnexpectedError } from 'n8n-workflow';
throw new UnexpectedError('message', { extra: { context } });
// DON'T use deprecated ApplicationError

Frontend:

Vue 3 Composition API (<script setup lang="ts">)
CSS variables (never hardcode px) - see /packages/frontend/AGENTS.md
All text via i18n ($t('key'))
data-testid for E2E (single value, no spaces)

Backend:

Controller → Service → Repository
Dependency injection via @n8n/di
Config via @n8n/config
Zod schemas for validation

Testing:

Vitest (unit), Playwright (E2E)
Mock external dependencies
Work from package directory: pushd packages/cli && pnpm test

Database:

SQLite/PostgreSQL only (app DB)
Exception: DB nodes (MySQL Node, etc.) can use DB-specific features

Commands:

pnpm build > build.log 2>&1  # Always redirect
pnpm typecheck               # Before commit
pnpm lint                    # Before commit

Key Packages

Package	Purpose
`packages/cli`	Backend API
`packages/frontend/editor-ui`	Vue 3 frontend
`packages/@n8n/api-types`	Shared types
`packages/@n8n/db`	TypeORM entities
`packages/workflow`	Core interfaces

Common Patterns

Pinia Store:

import { STORES } from '@n8n/stores';
export const useMyStore = defineStore(STORES.MY_STORE, () => {
  const state = shallowRef([]);
  return { state };
});

Vue Component:

<script setup lang="ts">
type Props = { title: string };
const props = defineProps<Props>();
</script>

Service:

import { Service } from '@n8n/di';
import { Config } from '@n8n/config';

@Service()
export class MyService {
  constructor(private readonly config: Config) {}
}

📖 Need more details? Read /AGENTS.md and /packages/frontend/AGENTS.md

Weekly Installs

274

Repository

n8n-io/n8n

GitHub Stars

181.1K

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketWarn SnykPass

Installed on

opencode265

codex264

gemini-cli262

github-copilot259

kimi-cli257

amp257

xdrop 文件传输脚本：Bun 环境下安全上传下载工具，支持加密分享

20,700 周安装