配置

所有 Finch 配置都存储在一个 FinchConfigs 实例中，该实例只创建一次并传递给 FinchApp。本页记录了每个选项及其对应的环境变量。

项目结构

典型的 Finch 项目结构如下：

.
├── lib/
│   ├── app.dart              # FinchApp 设置和 main()
│   ├── configs/
│   │   └── setting.dart      # 应用级常量（可选）
│   ├── controllers/
│   ├── models/
│   ├── db/
│   ├── route/
│   │   ├── web_route.dart
│   │   └── socket_route.dart
│   ├── languages/            # JSON 语言文件 (en.json, fa.json …)
│   └── widgets/              # Jinja 模板文件 (*.j2.html)
├── public/                   # 直接提供服务的静态文件
├── migrations/               # MySQL 迁移 SQL 文件
├── migrations_sqlite/        # SQLite 迁移 SQL 文件
├── .env
└── pubspec.yaml

FinchConfigs

FinchConfigs 是核心配置类。所有构造函数参数都有对应的 .env 回退值。

import 'package:finch/finch_app.dart';
import 'package:finch/finch_tools.dart'; // pathTo(), env

FinchConfigs configs = FinchConfigs(
  // --- 服务器 ---
  port: (env['DOMAIN_PORT'] ?? '8080').toInt(def: 8080),
  ip: '0.0.0.0',
  domain: env['DOMAIN'] ?? 'localhost',
  domainScheme: env['DOMAIN_SCHEME'] ?? 'http',

  // --- 路径 ---
  publicDir: pathTo(env['PUBLIC_DIR'] ?? './public'),
  widgetsPath: pathTo(env['WIDGETS_PATH'] ?? './lib/widgets'),
  widgetsType: env['WIDGETS_TYPE'] ?? 'j2.html',
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? './lib/languages'),
  pathCache: pathTo(env['PATH_CACHE'] ?? './cache_routes'),
  pathMigrationMySQL: './migrations',
  pathMigrationSQLite: './migrations_sqlite',

  // --- 语言 ---
  languageSource: LanguageSource.json, // 或 LanguageSource.dart
  // dartLanguages: languageDart,

  // --- 数据库 ---
  dbConfig: FinchDBConfig(
    enable: true,
    host: env['MONGODB_CONNECTION'] ?? 'localhost',
    port: env['MONGODB_PORT'] ?? '27017',
    user: env['MONGODB_USER'] ?? 'root',
    pass: env['MONGODB_PASSWORD'] ?? 'password',
    dbName: env['MONGODB_NAME'] ?? 'my_app',
    auth: env['MONGODB_AUTH'] ?? 'admin',
  ),
  mysqlConfig: FinchMysqlConfig(
    enable: true,
    host: env['MYSQL_HOST'] ?? 'localhost',
    port: (env['MYSQL_PORT'] ?? '3306').toInt(def: 3306),
    user: env['MYSQL_USER'] ?? 'db_user',
    pass: env['MYSQL_PASS'] ?? 'db_password',
    databaseName: env['MYSQL_DATABASE'] ?? 'my_db',
  ),
  sqliteConfig: FinchSqliteConfig(
    enable: true,
    filePath: env['SQLITE_PATH'] ?? './app.sqlite',
  ),

  // --- 邮件 ---
  mailDefault: '[email protected]',
  mailHost: 'smtp.example.com',

  // --- 模板引擎 (Jinja) ---
  blockStart: '{%',
  blockEnd: '%}',
  variableStart: '{{',
  variableEnd: '}}',
  commentStart: '{#',
  commentEnd: '#}',

  // --- 安全 ---
  cookiePassword: env['COOKIE_PASSWORD'] ?? 'change-me-in-production',

  // --- 开发 ---
  enableLocalDebugger: (env['ENABLE_LOCAL_DEBUGGER'] ?? false).toString().toBool,
);

关键属性参考

属性	类型	默认值	用途
`port`	`int`	`8080`	HTTP 服务器端口
`ip`	`String`	`'0.0.0.0'`	绑定地址
`domain`	`String`	`'localhost'`	公共域名
`domainScheme`	`String`	`'http'`	`http` 或 `https`
`domainPort`	`int`	同 `port`	生成 URL 中使用的端口
`publicDir`	`String`	`'public'`	静态文件根目录
`widgetsPath`	`String`	`'bin/widgets'`	模板目录
`widgetsType`	`String`	`'html'`	模板文件扩展名
`languagePath`	`String`	`'languages'`	JSON 语言文件目录
`languageSource`	`LanguageSource`	`.json`	`.json` 或 `.dart`
`pathCache`	`String`	`'./cache'`	路由响应缓存目录
`pathMigrationMySQL`	`String`	`'./migrations'`	MySQL 迁移目录
`pathMigrationSQLite`	`String`	`'./migrations_sqlite'`	SQLite 迁移目录
`cookiePassword`	`String`	`'password'`	加密 Cookie 的密钥
`enableLocalDebugger`	`bool`	`false`	在浏览器中启用调试栏
`fakeDelay`	`int`	`0`	添加人工响应延迟（毫秒）
`poweredBy`	`String`	`'Dart Finch'`	`X-Powered-By` 头部值
`noStop`	`bool`	`true`	未处理错误后保持服务器运行

数据库配置类

FinchDBConfig（MongoDB）

FinchDBConfig(
  enable: true,
  host: 'localhost',
  port: '27017',       // String
  user: 'root',
  pass: 'password',
  dbName: 'my_app',
  auth: 'admin',       // 认证源数据库
)

FinchMysqlConfig

FinchMysqlConfig(
  enable: true,
  host: 'localhost',
  port: 3306,          // int
  user: 'db_user',
  pass: 'db_password',
  databaseName: 'my_db',
  collation: 'utf8mb4_general_ci',
)

FinchSqliteConfig

FinchSqliteConfig(
  enable: true,
  filePath: './app.sqlite',
)

环境变量（.env）

Finch 会自动读取项目根目录中的 .env 文件。所有 FinchConfigs 值都可以通过环境变量覆盖。env 映射（来自 finch_tools.dart）同时提供 .env 和系统环境变量的访问。

DOMAIN_PORT=8080
DOMAIN=example.com
DOMAIN_SCHEME=https

MONGODB_CONNECTION=localhost
MONGODB_PORT=27017
MONGODB_USER=root
MONGODB_PASSWORD=secret
MONGODB_NAME=my_app
MONGODB_AUTH=admin

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=db_user
MYSQL_PASS=db_pass
MYSQL_DATABASE=my_db

SQLITE_PATH=./app.sqlite

ENABLE_LOCAL_DEBUGGER=true

isLocalDebug

FinchApp.config.isLocalDebug 在环境变量 LOCAL_DEBUG 设置为 true 时，或当 Dart 以调试模式运行（Console.isDebug）时返回 true。使用此标志来启用详细输出或本地调试栏。

if (FinchApp.config.isLocalDebug) {
  Console.p('调试模式已激活');
}

本页内容