laravel-11-12-app-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel 11/12 App Guidelines

Laravel 11/12 应用开发指南

Overview

概述

Apply a consistent workflow for Laravel 11/12 apps with optional frontend stacks, Dockerized commands, and Laravel Boost tooling.

为带有可选前端技术栈、Docker化命令和Laravel Boost工具的Laravel 11/12应用采用统一的工作流。

Quick Start

快速开始

Read repository instructions first:
```
AGENTS.md
```
. If
```
docs/
```
exists, read
```
docs/README.md
```
and relevant module docs before decisions.
Detect the stack and command locations; do not guess.
Use Laravel Boost
```
search-docs
```
for Laravel ecosystem guidance; use Context7 only if Boost docs are unavailable.
Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

首先阅读仓库说明：
```
AGENTS.md
```
。如果存在
```
docs/
```
目录，请在做决策前阅读
```
docs/README.md
```
及相关模块文档。
检测技术栈和命令位置，切勿猜测。
使用Laravel Boost的
```
search-docs
```
获取Laravel生态系统指南；仅当Boost文档不可用时才使用Context7。
遵循仓库的命名规范、UI语言、文档优先策略以及现有组件模式。

Stack Detection

技术栈检测

Check
```
composer.json
```
,
```
package.json
```
,
```
docker-compose.*
```
, and
```
config/*
```
to confirm:
- Docker Compose/Sail vs host commands
- API-only vs full-stack
- Frontend framework (Inertia/React, Livewire, Vue, Blade)
- Auth (Fortify, Sanctum, Passport, custom)

检查
```
composer.json
```
、
```
package.json
```
、
```
docker-compose.*
```
和
```
config/*
```
文件以确认：
- 使用Docker Compose/Sail还是本地主机命令
- 仅API还是全栈模式
- 前端框架（Inertia/React、Livewire、Vue、Blade）
- 认证方式（Fortify、Sanctum、Passport、自定义）

Laravel 11/12 Core Conventions

Laravel 11/12 核心规范

Use the Laravel 11/12 structure: configure middleware, exceptions, and routes in
```
bootstrap/app.php
```
; service providers in
```
bootstrap/providers.php
```
; console configuration in
```
routes/console.php
```
.
Use Eloquent models and relationships first; avoid raw queries and
```
DB::
```
unless truly necessary.
Create Form Request classes for validation instead of inline validation.
Prefer named routes and
```
route()
```
for URL generation.
When altering columns, include all existing attributes in the migration to avoid dropping them.
Ask before destructive database operations (e.g., reset/rollback/fresh).

采用Laravel 11/12的结构：在
```
bootstrap/app.php
```
中配置中间件、异常和路由；在
```
bootstrap/providers.php
```
中配置服务提供者；在
```
routes/console.php
```
中配置控制台命令。
优先使用Eloquent模型及关联关系；除非确有必要，否则避免使用原生查询和
```
DB::
```
方法。
创建Form Request类进行验证，而非内联验证。
优先使用命名路由和
```
route()
```
方法生成URL。
修改数据库列时，迁移文件中需包含所有现有属性，避免意外删除。
执行破坏性数据库操作（如重置/回滚/刷新）前需确认。

API-Only Mode

仅API模式

Use
```
routes/api.php
```
; avoid Inertia and frontend assumptions.
Prefer API Resources and versioning if the repo already uses them.
Follow the repo's auth stack (Sanctum/Passport/custom) and response format conventions.
Do not require Vite/Tailwind/NPM unless the repo already includes them.

使用
```
routes/api.php
```
；避免依赖Inertia和前端相关假设。
如果仓库已使用API资源和版本控制，请遵循该规范。
遵循仓库的认证技术栈（Sanctum/Passport/自定义）和响应格式规范。
除非仓库已包含Vite/Tailwind/NPM，否则不要强制要求使用。

Inertia + React + Wayfinder (if present)

Inertia + React + Wayfinder（若存在）

Use
```
Inertia::render()
```
for server-side routing; place pages under
```
resources/js/Pages
```
unless the repo says otherwise.
Use
```
<Form>
```
or
```
useForm
```
for Inertia forms; add skeleton/empty states for deferred props.
Use
```
<Link>
```
or
```
router.visit()
```
for navigation.
Use Wayfinder named imports for tree-shaking; avoid default imports; regenerate routes after changes if required.

使用
```
Inertia::render()
```
进行服务端路由；页面默认放在
```
resources/js/Pages
```
目录下，除非仓库另有规定。
使用
```
<Form>
```
或
```
useForm
```
处理Inertia表单；为延迟加载的属性添加骨架屏/空状态。
使用
```
<Link>
```
或
```
router.visit()
```
进行导航。
使用Wayfinder的命名导入以实现树摇优化；避免默认导入；修改后若需要则重新生成路由。

Livewire / Vue / Blade (if present)

Livewire / Vue / Blade（若存在）

Follow existing component patterns and conventions; do not mix frameworks unless the repo already does.
Keep UI strings in the repo's expected language.

遵循现有组件模式和规范；除非仓库已混合使用，否则不要混用框架。
UI文本需符合仓库指定的语言。

Tailwind CSS v4 (if present)

Tailwind CSS v4（若存在）

Use
```
@import "tailwindcss";
```
and
```
@theme
```
for tokens.
Avoid deprecated utilities; use replacements (e.g.,
```
shrink-*
```
,
```
grow-*
```
,
```
text-ellipsis
```
).
Use
```
gap-*
```
for spacing between items; follow existing dark mode conventions if present.

使用
```
@import "tailwindcss";
```
和
```
@theme
```
定义令牌。
避免使用已废弃的工具类；使用替代方案（如
```
shrink-*
```
、
```
grow-*
```
、
```
text-ellipsis
```
）。
使用
```
gap-*
```
设置元素间距；若存在暗色模式规范，请遵循。

Testing and Formatting

测试与格式化

Use PHPUnit; generate tests with
```
php artisan make:test --phpunit
```
and prefer feature tests.
Run the minimal relevant tests (
```
php artisan test <file>
```
or
```
--filter=
```
).
Run
```
vendor/bin/pint --dirty
```
before finalizing code changes.
After minimal tests pass, offer to run the full test suite.

使用PHPUnit；通过
```
php artisan make:test --phpunit
```
生成测试，优先编写功能测试。
运行最小范围的相关测试（
```
php artisan test <file>
```
或
```
--filter=
```
参数）。
最终确定代码修改前，运行
```
vendor/bin/pint --dirty
```
。
最小范围测试通过后，可主动提出运行完整测试套件。

Laravel Boost MCP Tools (when available)

Laravel Boost MCP工具（若可用）

```
search-docs
```
before changing behavior or using framework features.
```
list-artisan-commands
```
to confirm Artisan options.
```
list-routes
```
to inspect routing changes.
```
tinker
```
for PHP debugging and
```
database-query
```
for read-only DB checks.
```
browser-logs
```
to inspect frontend errors.
```
get-absolute-url
```
for sharing project URLs.
See
```
references/boost-tools.md
```
for query patterns and tool usage tips.

修改行为或使用框架功能前，先使用
```
search-docs
```
。
使用
```
list-artisan-commands
```
确认Artisan命令选项。
使用
```
list-routes
```
检查路由变更。
使用
```
tinker
```
进行PHP调试，使用
```
database-query
```
进行只读数据库检查。
使用
```
browser-logs
```
查看前端错误。
使用
```
get-absolute-url
```
分享项目URL。
查看
```
references/boost-tools.md
```
获取查询模式和工具使用技巧。

Output Expectations

输出要求

Preserve existing architecture, structure, and dependencies unless the user explicitly requests changes.
Reuse existing components and follow local patterns.
Ask concise clarifying questions when repo guidance is missing or ambiguous.

除非用户明确要求更改，否则保留现有架构、结构和依赖。
复用现有组件并遵循本地模式。
当仓库指南缺失或模糊时，提出简洁的澄清问题。